Merge branch 'main' into automation/metadata-litellm-1.105.0-20261011

Author: isaacbmiller

.github/workflows/run_tests.yml

@@ -70,18 +70,31 @@ jobs:
   test:
     name: Run Tests
     runs-on: ubuntu-latest
+    # 3.15 is an allowed failure (see the matrix note). Tolerating it stops a
+    # failure from failing the workflow and, under the default fail-fast, from
+    # cancelling the 3.10-3.14 legs.
+    continue-on-error: ${{ matrix.python-version == '3.15' }}
+    env:
+      # fastuuid has no cp315 wheel and its pyo3 rejects 3.15; build it against
+      # the stable ABI on the 3.15 leg. pyo3 reads only the value "1".
+      PYO3_USE_ABI3_FORWARD_COMPATIBILITY: ${{ matrix.python-version == '3.15' && '1' || '0' }}
     permissions:
       contents: read
     strategy:
       matrix:
-        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+        # 3.15 is an allowed failure (continue-on-error above) while Python 3.15
+        # is a release candidate. Its deps install from cp315 wheels except
+        # fastuuid (a litellm dep), whose pyo3 rejects a Python past 3.14; the
+        # job env builds it against the stable ABI on the 3.15 leg only.
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14", "3.15"]
     steps:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           persist-credentials: false
       - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: ${{ matrix.python-version }}
+          allow-prereleases: true
       - name: Install uv with caching
         uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
@@ -103,18 +116,27 @@ jobs:
   extra_test:
     name: Run Extra and Deno Tests
     runs-on: ubuntu-latest
+    # 3.15 is an allowed failure (see the note in the `test` job); tolerated so
+    # it does not fail the workflow or, under fail-fast, cancel the 3.10-3.14 legs.
+    continue-on-error: ${{ matrix.python-version == '3.15' }}
+    env:
+      # fastuuid has no cp315 wheel and its pyo3 rejects 3.15; build it against
+      # the stable ABI on the 3.15 leg. pyo3 reads only the value "1".
+      PYO3_USE_ABI3_FORWARD_COMPATIBILITY: ${{ matrix.python-version == '3.15' && '1' || '0' }}
     permissions:
       contents: read
     strategy:
       matrix:
-        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+        # 3.15 is an allowed failure (see the note in the `test` job above).
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14", "3.15"]
     steps:
       - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           persist-credentials: false
       - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: ${{ matrix.python-version }}
+          allow-prereleases: true
       - name: Install uv with caching
         uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
@@ -256,18 +278,27 @@ jobs:
   build_package:
     name: Build Package
     runs-on: ubuntu-latest
+    # 3.15 is an allowed failure (see the note in the `test` job); tolerated so
+    # it does not fail the workflow or, under fail-fast, cancel the 3.10-3.14 legs.
+    continue-on-error: ${{ matrix.python-version == '3.15' }}
+    env:
+      # fastuuid has no cp315 wheel and its pyo3 rejects 3.15; build it against
+      # the stable ABI on the 3.15 leg. pyo3 reads only the value "1".
+      PYO3_USE_ABI3_FORWARD_COMPATIBILITY: ${{ matrix.python-version == '3.15' && '1' || '0' }}
     permissions:
       contents: read
     strategy:
       matrix:
-        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+        # 3.15 is an allowed failure (see the note in the `test` job above).
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14", "3.15"]
     steps:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           persist-credentials: false
       - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: ${{ matrix.python-version }}
+          allow-prereleases: true
       - name: Install uv with caching
         uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:

CONTRIBUTING.md

@@ -165,6 +165,8 @@ AI-assisted contributions are welcome under these conditions:
 
 - If you can't explain your changes without consulting an AI, don't submit the PR.
 - Disclose what AI tool you used and how in your PR description.
+- Agents must disclose in the PR description whether the contribution comes from a sweep for issues, a problem encountered during normal usage, or another origin.
+  State which applies, or provide a non-sensitive description of another origin. Do not share private or sensitive information about the use case.
 - Share your prompts. It helps reviewers and shows you thought through the problem.
 - Verify AI-found bugs yourself. Reproduce and confirm before filing. Write the report in
   your own words.

docs/docs/api/modules/Flex.md

@@ -84,7 +84,7 @@ The `program_trace` parameter is opt-in *by declaration*: only metrics that name
 
 ## Interpreter Execution
 
-`Flex` always runs its generated code through a `CodeInterpreter`. `interpreter_factory` defaults to `dspy.PythonInterpreter` (Deno/Pyodide) and must be a **zero-argument factory** returning a fresh interpreter; a bare instance is not accepted, so parallel evaluations receive isolated sessions. `dspy.configure(interpreter_factory=...)` replaces that default. A factory passed to `Flex` wins, unless it is `PythonInterpreter`. The factory is called once per interpreter session, including separate sessions requested by nested code-executing modules. With the default interpreter, optimizer-authored control flow, string work, arithmetic, and supported imports run inside the sandbox, and only provided-tool calls, predictor construction, and predictor calls bridge back to the host, which makes the real LM calls. Custom factories define their own trust boundary: `dspy.LocalInterpreter`, for example, separates process memory and stdout but retains the host user's filesystem, environment, credentials, network, and process authority.
+`Flex` always runs its generated code through a `CodeInterpreter`. `interpreter_factory` defaults to `dspy.PythonInterpreter` (Deno/Pyodide) and must be a **zero-argument factory** returning a fresh interpreter; a bare instance is not accepted, so parallel evaluations receive isolated sessions. `dspy.configure(interpreter_factory=...)` replaces that default. A factory passed to `Flex` wins, unless it is `PythonInterpreter`. The factory is called once per interpreter session, including separate sessions requested by nested code-executing modules. With the default interpreter, optimizer-authored control flow, string work, arithmetic, and supported imports run inside the sandbox, and only provided-tool calls, predictor construction, and predictor calls bridge back to the host, which makes the real LM calls. Custom factories define their own trust boundary: `dspy.LocalInterpreter`, for example, separates process memory and stdout but retains the host user's filesystem, environment, credentials, network, and process authority. An in-process interpreter that runs code with `exec()` in the host works, but isolates nothing; use one only for trusted code.
 
 Because the default builds a `PythonInterpreter`, *running* a `Flex` needs [Deno](https://deno.land/) installed; without it, the call raises.
 

docs/docs/diving-deeper/flex.md

@@ -34,7 +34,7 @@ The reflection model authors code, and code can be wrong. A candidate that doesn
 
 ### 7. Generated code always runs through an interpreter
 
-`Flex` takes its interpreter from `interpreter_factory`, else from `dspy.settings.interpreter_factory`, else from `dspy.PythonInterpreter` (Deno/Pyodide). Each of those must be a *zero-argument factory* — a bare instance or `None` is rejected. With the default, everything stays in the sandbox except provided-tool calls, predictor construction, and predictor calls, which bridge back to the host. Custom factories define their own trust boundary: `LocalInterpreter` separates process memory and stdout but retains the host user's filesystem, environment, credentials, network, and process authority. The factory creates a fresh interpreter for each session; a forward owns an outer session and nested code-executing modules may request separate sessions. Source portability between custom interpreters is not guaranteed. `max_predictor_calls` caps how many predictor calls the generated code can make in one `forward`.
+`Flex` takes its interpreter from `interpreter_factory`, else from `dspy.settings.interpreter_factory`, else from `dspy.PythonInterpreter` (Deno/Pyodide). Each of those must be a *zero-argument factory* — a bare instance or `None` is rejected. With the default, everything stays in the sandbox except provided-tool calls, predictor construction, and predictor calls, which bridge back to the host. Custom factories define their own trust boundary: `LocalInterpreter` separates process memory and stdout but retains the host user's filesystem, environment, credentials, network, and process authority. An in-process interpreter (one that runs code with `exec()` in the host, such as `dspy_interpreters.InProcessInterpreter`) works but isolates nothing: generated code shares the host's memory, so `max_predictor_calls` and the bridged LM-option allowlist bind only well-behaved code. Use one only for code you trust. The facade binds `dspy` in that interpreter's namespace and leaves the host's `dspy` module in place. The factory creates a fresh interpreter for each session; a forward owns an outer session and nested code-executing modules may request separate sessions. Source portability between custom interpreters is not guaranteed. `max_predictor_calls` caps how many predictor calls the generated code can make in one `forward`.
 
 ### 8. The declared output types are enforced at the sandbox boundary
 

docs/requirements.txt

@@ -2,7 +2,7 @@ beautifulsoup4==4.15.0
 markdownify==1.2.3
 mdformat==0.7.22
 mdformat-tables==1.0.0
-mkdocstrings==1.0.6
+mkdocstrings==1.0.7
 mkdocstrings-python==2.0.9
 nbconvert==7.17.1
 pillow==12.3.0

dspy/adapters/two_step_adapter.py

@@ -194,7 +194,10 @@ def format_user_message_content(
         inputs: dict[str, Any],
         prefix: str = "",
         suffix: str = "",
+        main_request: bool = False,
     ) -> str:
+        # `main_request` is accepted for compatibility with the base Adapter contract; the first-stage prompt has no
+        # output-format reminder to add.
         parts = [prefix]
 
         for name in signature.input_fields.keys():

dspy/adapters/utils.py

@@ -71,11 +71,11 @@ def serialize_for_json(value: Any) -> Any:
     Returns:
         The formatted value, which is serializable as a JSON string.
     """
-    # Attempt to format the value as a JSON-compatible object using pydantic, falling back to
-    # a string representation of the value if that fails (e.g. if the value contains an object
-    # that pydantic doesn't recognize or can't serialize)
+    # Format the value as a JSON-compatible object using pydantic. A nested value pydantic can't
+    # serialize (e.g. a numpy scalar) becomes its string form without affecting its siblings; the
+    # whole value falls back to its string form only if pydantic can't handle it at all.
     try:
-        return TypeAdapter(type(value)).dump_python(value, mode="json")
+        return TypeAdapter(type(value)).dump_python(value, mode="json", fallback=str)
     except Exception:
         return str(value)
 

dspy/predict/rlm.py

@@ -588,8 +588,9 @@ def _setup_facade(
         )
         try:
             invocation.install(repl)
-        except CodeExecutionError as e:
-            # The runtime cannot host the shim (e.g. it runs code in the host's memory): no sub-agents this call.
+        except (CodeExecutionError, SyntaxError) as e:
+            # The runtime cannot host the shim (e.g. a restricted compiler rejects the shim's `_dspy_*` names):
+            # no sub-agents this call.
             for name in (CONSTRUCT_TOOL, CALL_TOOL):
                 repl.tools.pop(name, None)
             logger.warning("RLM sub-agents are unavailable on %s: %s", type(repl).__name__, e)

dspy/primitives/_facade_shim.py

@@ -149,13 +149,24 @@ def _dspy_tool(func, **_kw):
 dspy = _dspy
 
 # Register as the importable ``dspy`` only inside the sandbox, where the registered host tools are
-# present in globals(). A sandbox whose ``dspy`` is the host's own module image (the host process or a
-# fork of it) would hand generated code the host's memory, so the facade refuses it.
+# present in globals(). An interpreter that runs code in the host's memory (the host process or a fork
+# of it) shares the host's sys.modules, so there ``import dspy`` resolves to the shim through this
+# namespace's own __import__ and the host's ``dspy`` module stays in place.
 if "__dspy_construct__" in globals():
     _dspy_host_facade = getattr(_dspy_sys, "modules", {}).get("dspy.primitives.facade")
     if getattr(_dspy_host_facade, "_HOST_PROCESS_TOKEN", None) == __dspy_host_token:  # noqa: F821 - host-injected
-        raise RuntimeError(
-            "This interpreter runs code in the host's memory (the host process or a fork of it); "
-            "the dspy facade needs an isolated interpreter."
-        )
-    _dspy_sys.modules["dspy"] = _dspy
+        _dspy_builtins = globals()["__builtins__"]
+        _dspy_builtins = dict(_dspy_builtins if isinstance(_dspy_builtins, dict) else vars(_dspy_builtins))
+        _dspy_import_orig = _dspy_builtins["__import__"]
+
+        def _dspy_import(name, globals=None, locals=None, fromlist=(), level=0):
+            if level == 0 and name.split(".")[0] == "dspy":
+                if name != "dspy":
+                    raise ModuleNotFoundError(f"No module named {name!r}; 'dspy' is not a package", name=name)
+                return _dspy
+            return _dspy_import_orig(name, globals, locals, fromlist, level)
+
+        _dspy_builtins["__import__"] = _dspy_import
+        globals()["__builtins__"] = _dspy_builtins
+    else:
+        _dspy_sys.modules["dspy"] = _dspy

dspy/primitives/code_interpreter.py

@@ -84,8 +84,9 @@ class CodeInterpreter(Protocol):
     Sandbox dspy facade:
         dspy.Flex and dspy.RLM install a ``dspy`` shim whose predictors are built and
         run on the host, so registered tools must be callable as globals in executed
-        code and state must persist across execute() calls. The shim refuses an
-        interpreter that runs code in the host's memory (the host process or a fork).
+        code and state must persist across execute() calls. In an interpreter that runs
+        code in the host's memory, the shim binds ``dspy`` in that interpreter's namespace
+        and leaves the host's ``sys.modules`` alone.
     """
 
     @property