Skip to content

armgit / dspy

Public Imported from GitHub
0

DSPy: The framework for programming—not prompting—language models

Python

Add restrict_pickle option for safe disk cache deserialization (#9629)

Isaac Miller02ce8b24f9d6
diff --git a/docs/docs/tutorials/cache/index.md b/docs/docs/tutorials/cache/index.md
index 275882b3e..a10c4b709 100644
--- a/docs/docs/tutorials/cache/index.md
+++ b/docs/docs/tutorials/cache/index.md
@@ -81,6 +81,51 @@ This is especially beneficial when:
- Working with long system prompts that remain constant
- Making multiple requests with similar context
+## Restricting Pickle Deserialization
+
+By default, DSPy's on-disk cache uses Python's `pickle` for serialization. While this handles arbitrary Python objects, `pickle.load` can execute arbitrary code -- meaning a corrupted or malicious cache file could be dangerous.
+
+DSPy provides an opt-in `restrict_pickle` mode that restricts which types the cache is allowed to deserialize:
+
+```python
+dspy.configure_cache(restrict_pickle=True)
+```
+
+When enabled, the cache only allows:
+
+- **LiteLLM and OpenAI response types** (`litellm.types.*`, `openai.types.*`) -- the pydantic data models that DSPy caches for LM calls, embeddings, and the Responses API.
+- **NumPy array reconstruction helpers** -- the specific internal functions needed to deserialize `numpy.ndarray` (used by embedding caches).
+- **User-registered types** via `safe_types` -- any additional types you explicitly trust.
+
+If you cache custom types (dataclasses, pydantic models, etc.), register them:
+
+```python
+from dataclasses import dataclass
+
+@dataclass
+class MyResult:
+ score: float
+ label: str
+
+dspy.configure_cache(restrict_pickle=True, safe_types=[MyResult])
+```
+
+If a type is missing from the allowlist, the cache treats it as a miss and returns `None`. The log message will name the exact type that was rejected:
+
+```
+WARNING dspy.clients.cache: Failed to deserialize disk cache entry <key>
+```
+
+### Nested types
+
+If your registered type contains nested custom types, you must register all of them. For example, if `MyResult` contains a `Metadata` field, register both:
+
+```python
+dspy.configure_cache(restrict_pickle=True, safe_types=[MyResult, Metadata])
+```
+
+The error message will tell you exactly which nested type is missing.
+
## Disabling/Enabling DSPy Cache
There are scenarios where you might need to disable caching, either entirely or selectively for in-memory or on-disk caches. For instance:
diff --git a/dspy/clients/__init__.py b/dspy/clients/__init__.py
index 592a9091d..2d8909114 100644
--- a/dspy/clients/__init__.py
+++ b/dspy/clients/__init__.py
@@ -1,6 +1,7 @@
import logging
import os
from pathlib import Path
+from typing import Any
import litellm
@@ -22,6 +23,8 @@ def configure_cache(
disk_cache_dir: str | None = DISK_CACHE_DIR,
disk_size_limit_bytes: int | None = DISK_CACHE_LIMIT,
memory_max_entries: int = 1000000,
+ restrict_pickle: bool = False,
+ safe_types: list[type[Any]] | None = None,
):
"""Configure the cache for DSPy.
@@ -32,6 +35,9 @@ def configure_cache(
disk_size_limit_bytes: The size limit of the on-disk cache.
memory_max_entries: The maximum number of entries in the in-memory cache. To allow the cache to grow without
bounds, set this parameter to `math.inf` or a similar value.
+ restrict_pickle: When True, restrict pickle deserialization to a known-safe
+ set of types. When False (default), use unrestricted pickle.
+ safe_types: Additional types to allow when restrict_pickle is True.
"""
DSPY_CACHE = Cache(
@@ -40,6 +46,8 @@ def configure_cache(
disk_cache_dir,
disk_size_limit_bytes,
memory_max_entries,
+ restrict_pickle=restrict_pickle,
+ safe_types=safe_types,
)
import dspy
diff --git a/dspy/clients/cache.py b/dspy/clients/cache.py
index 6e52e74fe..28d350d18 100644
--- a/dspy/clients/cache.py
+++ b/dspy/clients/cache.py
@@ -13,6 +13,11 @@ import pydantic
from cachetools import LRUCache
from diskcache import FanoutCache
+from dspy.clients.disk_serialization import (
+ DeserializationError,
+ restricted_disk,
+)
+
logger = logging.getLogger(__name__)
@@ -47,6 +52,8 @@ class Cache:
disk_cache_dir: str | None,
disk_size_limit_bytes: int | None = 1024 * 1024 * 10,
memory_max_entries: int = 1000000,
+ restrict_pickle: bool = False,
+ safe_types: list[type[Any]] | None = None,
):
"""
Args:
@@ -55,6 +62,9 @@ class Cache:
disk_cache_dir: The directory where the disk cache is stored.
disk_size_limit_bytes: The maximum size of the disk cache (in bytes).
memory_max_entries: The maximum size of the in-memory cache (in number of items).
+ restrict_pickle: When True, restrict pickle deserialization to a known-safe
+ set of types. When False (default), use unrestricted pickle.
+ safe_types: Additional types to allow when restrict_pickle is True.
"""
self.enable_disk_cache = enable_disk_cache
@@ -69,12 +79,19 @@ class Cache:
else:
self.memory_cache = {}
if self.enable_disk_cache:
- self.disk_cache = FanoutCache(
+ fanout_kwargs = dict(
directory=self.disk_cache_dir,
shards=16,
timeout=10,
size_limit=disk_size_limit_bytes,
)
+ if restrict_pickle:
+ for t in safe_types or []:
+ if not isinstance(t, type):
+ raise TypeError(f"safe_types entries must be types, got {t!r}")
+ allowed = frozenset((cls.__module__, cls.__qualname__) for cls in (safe_types or []))
+ fanout_kwargs["disk"] = restricted_disk(allowed)
+ self.disk_cache = FanoutCache(**fanout_kwargs)
else:
self.disk_cache = {}
@@ -112,7 +129,13 @@ class Cache:
return self._prepare_cached_response(response)
if self.enable_disk_cache:
- response = self.disk_cache.get(key)
+ try:
+ response = self.disk_cache.get(key)
+ except DeserializationError:
+ logger.debug("Failed to deserialize disk cache entry %s", key)
+ self.disk_cache.delete(key)
+ return None
+
if response is None:
return None
diff --git a/dspy/clients/disk_serialization.py b/dspy/clients/disk_serialization.py
new file mode 100644
index 000000000..f57764933
--- /dev/null
+++ b/dspy/clients/disk_serialization.py
@@ -0,0 +1,88 @@
+"""Restricted pickle deserialization for disk cache.
+
+Provides a RestrictedDisk subclass that overrides diskcache's fetch to use
+a restricted unpickler.
+
+Trust model:
+- litellm.types.* and openai.types.* are trusted by module prefix (pydantic
+ data models only, forward-compatible with library upgrades)
+- numpy reconstruction helpers are trusted by exact (module, name) pairs
+- user safe_types are trusted by exact (module, qualname) pairs
+"""
+
+from __future__ import annotations
+
+import io
+import os.path
+import pickle
+from typing import Any
+
+from diskcache import Disk
+from diskcache.core import MODE_PICKLE
+
+_TRUSTED_MODULE_PREFIXES = (
+ "litellm.types.",
+ "openai.types.",
+)
+
+_NUMPY_ALLOWED: frozenset[tuple[str, str]] = frozenset({
+ ("numpy", "dtype"),
+ ("numpy", "ndarray"),
+ ("numpy._core.numeric", "_frombuffer"),
+ ("numpy.core.numeric", "_frombuffer"),
+ ("numpy.core.multiarray", "_reconstruct"),
+ ("numpy._core.multiarray", "_reconstruct"),
+ ("_codecs", "encode"),
+})
+
+
+class DeserializationError(Exception):
+ """Raised when a cached value cannot be deserialized."""
+
+
+class _RestrictedUnpickler(pickle.Unpickler):
+ _allowed: frozenset[tuple[str, str]] = frozenset()
+
+ def find_class(self, module: str, name: str) -> type:
+ if any(module.startswith(p) for p in _TRUSTED_MODULE_PREFIXES):
+ return super().find_class(module, name)
+ if (module, name) in _NUMPY_ALLOWED or (module, name) in self._allowed:
+ return super().find_class(module, name)
+ raise DeserializationError(
+ f"Type {module}.{name} is not in the safe_types allowlist. "
+ f"Register it via dspy.configure_cache(safe_types=[...])."
+ )
+
+
+def _restricted_load(f: Any, allowed: frozenset[tuple[str, str]]) -> Any:
+ unpickler = _RestrictedUnpickler(f)
+ unpickler._allowed = allowed
+ try:
+ return unpickler.load()
+ except DeserializationError:
+ raise
+ except Exception as e:
+ raise DeserializationError(f"Corrupt cache entry: {e}") from e
+
+
+class _RestrictedDisk(Disk):
+ """Disk subclass that restricts pickle deserialization to an allowlist."""
+
+ _allowed: frozenset[tuple[str, str]]
+
+ def fetch(self, mode, filename, value, read):
+ if mode == MODE_PICKLE:
+ if value is None:
+ with open(os.path.join(self._directory, filename), "rb") as f:
+ return _restricted_load(f, self._allowed)
+ return _restricted_load(io.BytesIO(value), self._allowed)
+ return super().fetch(mode, filename, value, read)
+
+
+def restricted_disk(allowed: frozenset[tuple[str, str]]) -> type[_RestrictedDisk]:
+ """Return a Disk subclass bound to the given allowlist.
+
+ diskcache expects ``disk=`` to be a class it instantiates itself, so
+ we return a subclass with ``_allowed`` baked in as a class attribute.
+ """
+ return type("RestrictedDisk", (_RestrictedDisk,), {"_allowed": allowed})
diff --git a/tests/clients/test_cache.py b/tests/clients/test_cache.py
index 1d7c0db83..bae3def2e 100644
--- a/tests/clients/test_cache.py
+++ b/tests/clients/test_cache.py
@@ -7,6 +7,7 @@ import pytest
from cachetools import LRUCache
from diskcache import FanoutCache
+import dspy
from dspy.clients.cache import Cache
@@ -16,6 +17,12 @@ class DummyResponse:
usage: dict
+@dataclass
+class CacheValidationDataclass:
+ name: str
+ value: int
+
+
@pytest.fixture
def cache_config(tmp_path):
"""Default cache configuration."""
@@ -34,6 +41,19 @@ def cache(cache_config):
return Cache(**cache_config)
+def restricted_cache(tmp_path):
+ """Create a cache instance with restricted pickle deserialization."""
+ return Cache(
+ enable_disk_cache=True,
+ enable_memory_cache=True,
+ disk_cache_dir=str(tmp_path / "restricted"),
+ disk_size_limit_bytes=1024 * 1024,
+ memory_max_entries=100,
+ restrict_pickle=True,
+ )
+
+
def test_initialization(tmp_path):
"""Test different cache initialization configurations."""
# Test memory-only cache
@@ -370,3 +390,146 @@ def test_cache_init_with_disk_disabled_and_none_dir():
)
assert cache.disk_cache_dir is None
assert cache.enable_disk_cache is False
+
+
+# -- restrict_pickle tests --
+
+
+def test_model_response_roundtrip_in_restricted_mode(restricted_cache):
+ from litellm import ModelResponse
+
+ response = ModelResponse(
+ id="test-123",
+ choices=[{"message": {"content": "cached response"}, "index": 0, "finish_reason": "stop"}],
+ usage={"prompt_tokens": 10, "completion_tokens": 5, "total_tokens": 15},
+ )
+ request = {"model": "openai/gpt-5-nano", "prompt": "test"}
+
+ restricted_cache.put(request, response)
+ restricted_cache.reset_memory_cache()
+
+ result = restricted_cache.get(request)
+ assert isinstance(result, ModelResponse)
+ assert result.choices[0].message.content == "cached response"
+
+
+def test_registered_dataclass_roundtrip_in_restricted_mode(tmp_path):
+ cache = Cache(
+ enable_disk_cache=True,
+ enable_memory_cache=False,
+ disk_cache_dir=str(tmp_path),
+ restrict_pickle=True,
+ safe_types=[CacheValidationDataclass],
+ )
+ request = {
+ "model": "test",
+ "prompt": "registered_dataclass_test",
+ "payload": CacheValidationDataclass(name="request", value=1),
+ }
+ response = CacheValidationDataclass(name="hello", value=3)
+
+ cache.put(request, response)
+ result = cache.get(request)
+
+ assert isinstance(result, CacheValidationDataclass)
+ assert result == response
+
+
+def test_configure_cache_registers_safe_types(tmp_path):
+ original_cache = dspy.cache
+ try:
+ dspy.configure_cache(
+ enable_disk_cache=True,
+ enable_memory_cache=False,
+ disk_cache_dir=str(tmp_path / "configured"),
+ restrict_pickle=True,
+ safe_types=[CacheValidationDataclass],
+ )
+ request = {"model": "test", "prompt": "configured_safe_type"}
+ response = CacheValidationDataclass(name="configured", value=7)
+
+ dspy.cache.put(request, response)
+ result = dspy.cache.get(request)
+
+ assert isinstance(result, CacheValidationDataclass)
+ assert result == response
+ finally:
+ dspy.cache = original_cache
+
+
+def test_corrupt_disk_entries_return_none(tmp_path):
+ """Real pickle corruption in a cache entry must return None, not raise."""
+ import sqlite3
+
+ cache = Cache(
+ enable_disk_cache=True,
+ enable_memory_cache=False,
+ disk_cache_dir=str(tmp_path),
+ restrict_pickle=True,
+ )
+ request = {"model": "test", "prompt": "will_be_corrupted"}
+ cache.put(request, {"value": "good"})
+ key = cache.cache_key(request)
+
+ # Corrupt the pickle blob in the SQLite database
+ for shard_id in range(16):
+ db_path = os.path.join(str(tmp_path), f"{shard_id:03d}", "cache.db")
+ if not os.path.exists(db_path):
+ continue
+ conn = sqlite3.connect(db_path)
+ row = conn.execute("SELECT rowid, value FROM Cache WHERE key = ?", (key,)).fetchone()
+ if row:
+ conn.execute("UPDATE Cache SET value = X'DEADBEEF' WHERE rowid = ?", (row[0],))
+ conn.commit()
+ conn.close()
+
+ assert cache.get(request) is None
+
+
+def test_restricted_and_unrestricted_share_wire_format(tmp_path):
+ """Both modes use standard pickle, so entries written by one can be read by the other."""
+ shared_dir = tmp_path / "shared"
+ request = {"model": "test", "prompt": "shared"}
+
+ unrestricted = Cache(
+ enable_disk_cache=True, enable_memory_cache=False,
+ disk_cache_dir=shared_dir, disk_size_limit_bytes=1024 * 1024,
+ )
+ unrestricted.put(request, {"value": "hello"})
+ unrestricted.disk_cache.close()
+
+ restricted = Cache(
+ enable_disk_cache=True, enable_memory_cache=False,
+ disk_cache_dir=shared_dir, disk_size_limit_bytes=1024 * 1024,
+ restrict_pickle=True,
+ )
+ assert restricted.get(request) == {"value": "hello"}
+
+
+@dataclass
+class _UnlistedDataclass:
+ value: int
+
+
+def test_unlisted_type_rejected_on_read(restricted_cache):
+ request = {"model": "test", "prompt": "dataclass"}
+
+ restricted_cache.put(request, _UnlistedDataclass(value=1))
+
+ # Memory cache still works
+ assert restricted_cache.get(request) == _UnlistedDataclass(value=1)
+
+ # After clearing memory, restricted unpickler rejects the unlisted type
+ restricted_cache.reset_memory_cache()
+ assert restricted_cache.get(request) is None
+
+
+def test_safe_types_rejects_non_types(tmp_path):
+ with pytest.raises(TypeError, match="safe_types entries must be types"):
+ Cache(
+ enable_disk_cache=True,
+ enable_memory_cache=False,
+ disk_cache_dir=str(tmp_path),
+ restrict_pickle=True,
+ safe_types=["not_a_type"],
+ )
diff --git a/tests/clients/test_disk_serialization.py b/tests/clients/test_disk_serialization.py
new file mode 100644
index 000000000..a7d7fcd47
--- /dev/null
+++ b/tests/clients/test_disk_serialization.py
@@ -0,0 +1,286 @@
+"""Tests for restricted pickle deserialization."""
+
+import io
+import pickle
+from dataclasses import dataclass
+
+import diskcache
+import numpy as np
+import pydantic
+import pytest
+from litellm.types.llms.openai import ResponseAPIUsage, ResponsesAPIResponse
+from litellm.types.utils import EmbeddingResponse, ModelResponse, TextCompletionResponse
+from openai.types.responses import ResponseOutputMessage, ResponseOutputText
+
+from dspy.clients.disk_serialization import (
+ DeserializationError,
+ _restricted_load,
+ restricted_disk,
+)
+
+
+class AllowedPydanticModel(pydantic.BaseModel):
+ name: str
+ value: int
+
+
+@dataclass
+class AllowedDataclass:
+ name: str
+ value: int
+
+
+class _UnlistedModel(pydantic.BaseModel):
+ value: int
+
+
+class _Outer:
+ @dataclass
+ class Inner:
+ value: int
+
+
+def _allowed_for(*types):
+ return frozenset((cls.__module__, cls.__qualname__) for cls in types)
+
+
+def _roundtrip(value, allowed=None):
+ """Pickle then restricted-unpickle."""
+ return _restricted_load(io.BytesIO(pickle.dumps(value)), allowed or set())
+
+
+# -- roundtrip tests (through diskcache) --
+
+def _make_cache(directory, allowed):
+ return diskcache.FanoutCache(
+ directory=directory,
+ shards=4,
+ disk=restricted_disk(allowed),
+ timeout=10,
+ )
+
+
+ {"a": 1, "b": [2, 3]},
+ [1, "two", 3.0],
+ "hello",
+ 42,
+ (1, 2, 3),
+], ids=["dict", "list", "str", "int", "tuple"])
+def test_plain_values_roundtrip(tmp_path, value):
+ cache = _make_cache(str(tmp_path), set())
+ cache["k"] = value
+ assert cache["k"] == value
+
+
+def test_pydantic_roundtrip(tmp_path):
+ allowed = _allowed_for(AllowedPydanticModel)
+ cache = _make_cache(str(tmp_path), allowed)
+ cache["k"] = AllowedPydanticModel(name="test", value=42)
+ assert cache["k"] == AllowedPydanticModel(name="test", value=42)
+
+
+def test_dataclass_roundtrip(tmp_path):
+ allowed = _allowed_for(AllowedDataclass)
+ cache = _make_cache(str(tmp_path), allowed)
+ cache["k"] = AllowedDataclass(name="test", value=42)
+ assert cache["k"] == AllowedDataclass(name="test", value=42)
+
+
+def test_ndarray_roundtrip(tmp_path):
+ cache = _make_cache(str(tmp_path), set())
+ value = np.arange(6, dtype=np.float32).reshape(2, 3)
+ cache["k"] = value
+ result = cache["k"]
+ assert isinstance(result, np.ndarray)
+ assert result.dtype == value.dtype
+ np.testing.assert_array_equal(result, value)
+
+
+def test_litellm_response_roundtrip(tmp_path):
+ cache = _make_cache(str(tmp_path), set())
+ response = ModelResponse(
+ id="chatcmpl-test",
+ choices=[{"message": {"content": "Hello"}, "index": 0, "finish_reason": "stop"}],
+ )
+ cache["k"] = response
+ result = cache["k"]
+ assert isinstance(result, ModelResponse)
+ assert result.choices[0].message.content == "Hello"
+
+
+def test_text_completion_response_roundtrip(tmp_path):
+ cache = _make_cache(str(tmp_path), set())
+ response = TextCompletionResponse(
+ id="cmpl-test", choices=[{"text": "Hello", "index": 0, "finish_reason": "stop"}], model="m",
+ )
+ cache["k"] = response
+ result = cache["k"]
+ assert isinstance(result, TextCompletionResponse)
+ assert result.choices[0]["text"] == "Hello"
+
+
+def test_embedding_response_roundtrip(tmp_path):
+ cache = _make_cache(str(tmp_path), set())
+ response = EmbeddingResponse(
+ data=[{"embedding": [0.1, 0.2], "index": 0, "object": "embedding"}],
+ model="m", usage={"prompt_tokens": 1, "total_tokens": 1},
+ )
+ cache["k"] = response
+ result = cache["k"]
+ assert isinstance(result, EmbeddingResponse)
+ assert result.data[0]["embedding"] == pytest.approx([0.1, 0.2])
+
+
+def test_responses_api_roundtrip(tmp_path):
+ """ResponsesAPIResponse with nested openai.types.responses.* classes."""
+ cache = _make_cache(str(tmp_path), set())
+ response = ResponsesAPIResponse(
+ id="resp_1",
+ created_at=0.0,
+ error=None,
+ incomplete_details=None,
+ instructions=None,
+ model="test",
+ object="response",
+ output=[
+ ResponseOutputMessage(
+ id="msg_1",
+ type="message",
+ status="completed",
+ role="assistant",
+ content=[ResponseOutputText(type="output_text", text="hello", annotations=[])],
+ ),
+ ],
+ metadata={},
+ parallel_tool_calls=False,
+ temperature=1.0,
+ tool_choice="auto",
+ tools=[],
+ top_p=1.0,
+ max_output_tokens=None,
+ previous_response_id=None,
+ reasoning=None,
+ status="completed",
+ text=None,
+ truncation="disabled",
+ usage=ResponseAPIUsage(input_tokens=1, output_tokens=1, total_tokens=2),
+ user=None,
+ )
+ cache["k"] = response
+ result = cache["k"]
+ assert isinstance(result, ResponsesAPIResponse)
+ assert result.output[0].content[0].text == "hello"
+
+
+def test_tool_call_response_roundtrip(tmp_path):
+ """ModelResponse with tool calls uses nested litellm types."""
+ cache = _make_cache(str(tmp_path), set())
+ response = ModelResponse(
+ id="chatcmpl-tool",
+ choices=[{
+ "message": {
+ "content": None,
+ "tool_calls": [{
+ "id": "call_1",
+ "type": "function",
+ "function": {"name": "get_weather", "arguments": '{"city":"SF"}'},
+ }],
+ },
+ "index": 0,
+ "finish_reason": "tool_calls",
+ }],
+ )
+ cache["k"] = response
+ result = cache["k"]
+ assert isinstance(result, ModelResponse)
+ assert result.choices[0].message.tool_calls[0].function.name == "get_weather"
+
+
+# -- allowlist enforcement --
+
+def test_unlisted_type_blocked_on_read(tmp_path):
+ cache = _make_cache(str(tmp_path), set())
+ cache["k"] = _UnlistedModel(value=1)
+ with pytest.raises(DeserializationError, match="not in the safe_types allowlist"):
+ cache["k"]
+
+
+def test_allowlists_are_isolated(tmp_path):
+ allowed = _allowed_for(AllowedPydanticModel)
+ cache = _make_cache(str(tmp_path / "a"), allowed)
+ cache["k"] = AllowedPydanticModel(name="test", value=1)
+ assert cache["k"] == AllowedPydanticModel(name="test", value=1)
+
+ empty_cache = _make_cache(str(tmp_path / "b"), set())
+ empty_cache["k"] = AllowedPydanticModel(name="test", value=1)
+ with pytest.raises(DeserializationError):
+ empty_cache["k"]
+
+
+def test_numpy_ctypeslib_blocked():
+ """Only specific numpy reconstruction functions are allowed, not arbitrary submodules."""
+ payload = (
+ b"\x80\x05" # PROTO 5
+ b"\x8c\x0fnumpy.ctypeslib" # SHORT_BINUNICODE (15 bytes)
+ b"\x8c\x0cload_library" # SHORT_BINUNICODE (12 bytes)
+ b"\x93" # STACK_GLOBAL
+ b"\x8c\x04evil" # SHORT_BINUNICODE "evil"
+ b"\x8c\x04/tmp" # SHORT_BINUNICODE "/tmp"
+ b"\x86" # TUPLE2
+ b"R" # REDUCE
+ b"." # STOP
+ )
+ with pytest.raises(DeserializationError):
+ _restricted_load(io.BytesIO(payload), set())
+
+
+# -- _restricted_load unit tests --
+
+def test_restricted_load_rejects_unknown_type():
+ data = pickle.dumps(_UnlistedModel(value=1))
+ with pytest.raises(DeserializationError, match="not in the safe_types allowlist"):
+ _restricted_load(io.BytesIO(data), set())
+
+
+def test_corrupt_pickle_raises_deserialization_error():
+ """Real pickle corruption must raise DeserializationError, not UnpicklingError."""
+ data = pickle.dumps({"key": "value"})
+ corrupted = data[:5] + b"nope" + data[9:]
+ with pytest.raises(DeserializationError, match="Corrupt cache entry"):
+ _restricted_load(io.BytesIO(corrupted), set())
+
+
+def test_nested_class_safe_types(tmp_path):
+ """safe_types must work for nested classes (pickle uses __qualname__)."""
+ allowed = _allowed_for(_Outer.Inner)
+ cache = _make_cache(str(tmp_path), allowed)
+ cache["k"] = _Outer.Inner(value=42)
+ assert cache["k"] == _Outer.Inner(value=42)
+
+
+def test_restricted_load_allows_builtin_types():
+ response = ModelResponse(
+ id="t", choices=[{"message": {"content": "hi"}, "index": 0, "finish_reason": "stop"}],
+ )
+ result = _roundtrip(response)
+ assert isinstance(result, ModelResponse)
+
+
+def test_all_cached_lm_types_roundtrip():
+ """Every LM return type that DSPy caches must roundtrip through the restricted unpickler."""
+ test_values = [
+ ModelResponse(
+ id="t", choices=[{"message": {"content": "hi"}, "index": 0, "finish_reason": "stop"}],
+ ),
+ TextCompletionResponse(
+ id="t", choices=[{"text": "hi", "index": 0, "finish_reason": "stop"}], model="m",
+ ),
+ EmbeddingResponse(
+ data=[{"embedding": [0.1], "index": 0, "object": "embedding"}],
+ model="m", usage={"prompt_tokens": 1, "total_tokens": 1},
+ ),
+ ]
+ for value in test_values:
+ result = _roundtrip(value)
+ assert type(result) is type(value), f"Failed roundtrip for {type(value).__name__}"
diff --git a/tests/clients/test_embedding.py b/tests/clients/test_embedding.py
index db6a4a845..ec83a944a 100644
--- a/tests/clients/test_embedding.py
+++ b/tests/clients/test_embedding.py
@@ -1,4 +1,4 @@
-from unittest.mock import patch
+from unittest.mock import MagicMock, patch
import numpy as np
import pytest
@@ -92,6 +92,36 @@ def test_callable_embedding(cache):
np.testing.assert_allclose(result, expected_embeddings)
+def test_callable_numpy_embedding_persists_to_disk(cache, tmp_path):
+ dspy.configure_cache(disk_cache_dir=tmp_path / ".dspy_cache_safe", restrict_pickle=True)
+
+ inputs = ["hello", "world"]
+ expected_embeddings = np.array(
+ [
+ [0.1, 0.2, 0.3],
+ [0.4, 0.5, 0.6],
+ ],
+ dtype=np.float32,
+ )
+
+ embedding_fn = MagicMock(return_value=expected_embeddings)
+ embedding = Embedder(embedding_fn)
+
+ result = embedding(inputs)
+ assert embedding_fn.call_count == 1
+ np.testing.assert_allclose(result, expected_embeddings)
+
+ result = embedding(inputs)
+ assert embedding_fn.call_count == 1
+ np.testing.assert_allclose(result, expected_embeddings)
+
+ dspy.cache.reset_memory_cache()
+
+ result = embedding(inputs)
+ assert embedding_fn.call_count == 1
+ np.testing.assert_allclose(result, expected_embeddings)
+
+
def test_invalid_model_type():
# Test that invalid model type raises ValueError
with pytest.raises(ValueError):