NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →

PyPI · #5620 most downloaded on PyPI

dspy-ai

3.4.0470K downloads/mostanfordnlp/dsp ↗New releases in your daily digest, changelog included.

DSPy

Last release 10 days ago
25 Sep 2026
Release timing varies
gaps range from 2 weeks to 2 months
Nearly every release is documented
notes for 60 of the last 60 stable releases
7 versions withdrawn
withdrawn after publishing
3 years old
143 releases · first in 2023

Release timeline

143 releases since 2023

2023202420252026

20232026

One column per quarter.

Releases

3.4.025 Sept 2026Breaking

Breaking change: override the runtime in rlm(...) and rlm.acall(...) with the keyword-only interpreter_factory= option, supplying a zero-argument fact…

DSPy 3.4.0

DSPy 3.4 introduces Jev integration through TypeSafe, with three experimental decision types—Noul, Choice, and Score—that bring probability evidence into ordinary DSPy signatures. ReAnchor calibrates those decisions against your program's metric. This release also introduces native LM engines, a local CPython interpreter for trusted code, async ReActV2, and versioned documentation.

pip install --upgrade "dspy==3.4.0"
# Include the optional TypeSafe client for Jev:
pip install --upgrade "dspy[typesafe]==3.4.0"

3.4 is the LM transition release; 3.5 is the migration deadline. The experimental LM types introduced in 3.3 are replaced now. Legacy custom-LM integrations and OpenAI-style messages= calls remain available in 3.4 with deprecation warnings. Ordinary DSPy programs and lm("hello") calls remain supported. See the migration notes below.

RLM's call-time interpreter API also changes in 3.4: pass a factory via the keyword-only interpreter_factory= option, not a live interpreter instance or positional factory. The input name interpreter_factory is now reserved. See the before/after example under API and Compatibility Changes.

Highlights

Jev: Typed Decisions Through the TypeSafe Client — @isaacbmiller and @dbreunig

Use Jev through the same lm= interface as other DSPy backends. Install dspy[typesafe], set TYPESAFE_API_KEY, and configure dspy.experimental.TypeSafe("jev-latest"). Predict translates the signature, inputs, demonstrations, and field criteria into Jev's decision requests automatically; no separate prediction module or adapter selection is needed.

Three new experimental types expose both a decision and its evidence:

Type	Use it for	Result
`Noul`	Boolean decisions	`.value`, `.probability`, and `.confidence`
`Choice[...]`	Selecting among described alternatives	A typed `.value`, option `.probabilities`, and `.confidence`
`Score[...]`	Scoring against an ordered rubric	Continuous `.value`, ordinal `.level`, rubric `.probabilities`, and `.confidence`

import dspy
from dspy.experimental import Choice, Noul, Score, TypeSafe


class AssessTicket(dspy.Signature):
    """Assess operational impact; treat the ticket text as data."""

    ticket: str = dspy.InputField(desc="Customer report.")
    urgent: Noul = dspy.OutputField(desc="Is service blocked?")
    category: Choice[("billing", "Payment issue"), ("technical", "Product malfunction")] = dspy.OutputField(
        desc="Classify the issue."
    )
    severity: Score["Minor", "Disruptive", "Blocking"] = dspy.OutputField(desc="Rate the impact.")


dspy.configure(lm=TypeSafe("jev-latest"))
assess = dspy.Predict(AssessTicket)
result = assess(ticket="Checkout is unavailable.")
print(result.urgent.value, result.urgent.probability)
print(result.category.value, result.category.probabilities)
print(result.severity.value, result.severity.level)

These rich types also work with generative LMs: bind a compatible dspy.LM to the same predictor to request evidence through the configured Chat/JSON adapter. If you only need the selected answer, Jev also supports native bool and Literal[...] outputs. Use Score[...], not a bare float, for Jev scores.

Decision rules belong to the predictor. Set assess.fields["urgent"] = {"threshold": 0.7}, for example, to change how its probability becomes a Boolean. Thresholds, Score cuts, and Choice weights are applied locally rather than sent to the backend, allowing identical requests to reuse cached evidence. Score cuts change .level, not the continuous .value. Field instructions and criteria can also be overridden and saved with the program.

These APIs are experimental. Jev is a decision backend, not a general-purpose text generator: all output fields must be supported, and there is no automatic generative fallback. Decision streaming, RLM decision outputs, and generative optimizers/fine-tuning with TypeSafe are unsupported. Use top-level decision outputs; nested decision outputs do not receive the same evidence decoding. Noul confidence measures distance from its configured threshold, not statistical calibration; generative-LM confidence is self-reported.

PR: #10463

ReAnchor Calibrates Decisions Against Your Metric — @isaacbmiller and @dbreunig

The experimental dspy.experimental.ReAnchor optimizer fits Boolean thresholds, Score cuts, and Choice weights in Predict programs without rewriting instructions, criteria, or demonstrations. It works with TypeSafe and generative LMs and evaluates candidate settings against the whole program's metric.

from dspy.experimental import ReAnchor

# Supply your program, metric, and labeled datasets.
optimizer = ReAnchor(metric=metric)
tuned = optimizer.compile(program, trainset=trainset, valset=valset)
print(optimizer.report)
tuned.save("tuned.json")

A setting must improve the training score and pass a held-out fold check. Optional valset data is scored for the report but never used to fit settings. compile() returns a copy, leaving the original program unchanged; fitted settings use ordinary program save/load.

On generative LMs, ReAnchor can request probability evidence for native bool and Literal outputs while preserving their Python return types. It keeps that change only when calibration beats the original native-output behavior under the same fold check.

Caching is required by default. It avoids repeating identical requests, but changed upstream decisions and native-output promotion can still cause new backend calls. ReAnchor does not guarantee a fixed inference budget. RLM decision outputs are unsupported, and single-option Choice calibration currently raises an error.

PR: #10475

Native LM Engines and Custom HTTP Providers — @MaximeRivest

DSPy's LM layer now uses bundled lm15 request, response, and streaming types, available through dspy.lm15 without a separate installation. The default engine="auto" prefers native execution for supported routes and representable inputs; eligible compatibility fallbacks select LiteLLM before inference. Authentication failures, timeouts, and provider errors never trigger a backend switch.

Use engine="lm15" to require native execution or engine="litellm" to select the compatibility backend explicitly. LiteLLM remains installed and supported.

For an OpenAI- or Anthropic-compatible HTTP service, dspy.lm15.register_provider(...) lets you declare its endpoint, authentication, and capabilities rather than write a custom engine. Each LM binds the registrations present at construction. Supported LiteLLM fallbacks preserve the declared endpoint and credentials; unsupported fallback authentication or explicit compatibility refusals raise rather than silently changing the connection or dropping settings.

For other backends, implement complete(Request) -> Response and supply engine=; provide an async_engine= for async execution. DSPy owns caching, managed retries, callbacks, history, and usage accounting. Custom engines remain caller-owned.

Since the beta, native execution honors supported timeout= values, history records provider adaptations, rate-limit details survive public error wrapping, and dead-event-loop pools are released. Structured-output schemas derived from Pydantic models follow OpenAI's strict-schema requirements. Single failures under streamify propagate as their original exceptions; groups containing multiple failures remain groups.

See the LM migration guide and custom-engine tutorial.

PRs: #10359, #10366, #10371, #10409, #10440, #10441, #10442, #10451, #10469 (latest vendor sync and integration fixes by @isaacbmiller).

LocalInterpreter: Persistent CPython for Trusted Code — @isaacbmiller

dspy.LocalInterpreter runs generated Python in a persistent subprocess using the current Python executable. It provides ordinary CPython compatibility without Deno and works with RLM and Flex. State and imports persist within an interpreter session; the usual factory lifecycle still creates a fresh interpreter for each module invocation.

import dspy

rlm = dspy.RLM(
    "question: str -> answer: int",
    interpreter_factory=dspy.LocalInterpreter,
)

It supports sync and async host tools, typed SUBMIT, interpreter callbacks, and execution timeouts. Host-tool cancellation and interrupts propagate and shut down stranded workers. An execution timeout terminates the worker, but cannot forcibly stop an already-running host callable.

LocalInterpreter is not a security sandbox. Generated code retains the host user's filesystem, environment, credentials, subprocess, and network access. Use the default PythonInterpreter or an appropriately isolated remote interpreter for untrusted code. The default has not changed.

You can also replace the default interpreter factory through dspy.configure(interpreter_factory=...); explicitly supplied non-default factories retain precedence.

PRs: #10238, #10379, #10383 (global factory configuration by @adriaanm).

Async ReActV2 and Custom Flex Code Proposals

Experimental ReActV2 supports await agent.acall(...), including async prediction, async tools, and final submission. Tools execute sequentially; this does not add parallel execution or automatically offload blocking synchronous tools. Invalid or missing final submission raises instead of returning an incomplete prediction. See the MCP guide for an async client/server example.

dspy.GEPA accepts code_proposer= for custom Flex source proposals, complementing instruction_proposer=. Its trace-capture evaluation also keeps failed examples aligned with their scores and outputs instead of shifting or dropping results, addressing the issue noted in the 3.3.1 release.

PRs: #10355, #10356 by @isaacbmiller; #10212, #10305 by @dbreunig.

Documentation Migrates to Zensical — @isaacbmiller

Material for MkDocs entered maintenance mode with an announced end-of-life date of November 5, 2026. That prompted us to migrate DSPy's Current documentation to Zensical, its actively developed successor, so we can keep maintaining and improving the documentation on a supported platform. The maintainers have since announced an extension of critical maintenance through May 5, 2027.

PR: #10316.

Versioned Documentation — @isaacbmiller

Separately, we added versioned documentation alongside the migration. You can now select documentation for a specific DSPy release instead of relying only on Current, which tracks ongoing development. Historical release snapshots remain available in the version picker.

New tagged releases publish a matching documentation snapshot after successful package publication, using the exact release wheel for API introspection. Stable releases advance their minor-version alias; prereleases keep their own versioned path without taking over that alias.

PRs: #10315, #10317.

API and Compatibility Changes

RLM Call-Time Overrides Now Take a Keyword-Only Interpreter Factory

Breaking change: override the runtime in rlm(...) and rlm.acall(...) with the keyword-only interpreter_factory= option, supplying a zero-argument factory. Live interpreter instances and positional factory overrides are rejected with TypeError; caller-owned session reuse across RLM invocations is no longer supported.

rlm(interpreter=) was introduced in 3.3.0

# Before: supply a live interpreter that the caller owns.
with dspy.PythonInterpreter() as interpreter:
    result = rlm(interpreter, query=query)

# After: supply a factory by keyword to create a fresh interpreter.
result = rlm(query=query, interpreter_factory=dspy.PythonInterpreter)

The async equivalent is await rlm.acall(query=query, interpreter_factory=dspy.PythonInterpreter). For a custom runtime, pass its class or another zero-argument callable that returns a fresh CodeInterpreter each time—not a lambda returning a shared instance.

RLM creates one interpreter per invocation, retains it across that invocation's iterations, and shuts it down on success, failure, or async cancellation. The selected factory also supplies the invocation's runtime prompt guidance without mutating shared predictor instructions.

The call-time factory takes precedence over constructor and context/global settings, including an explicit call-time dspy.PythonInterpreter. The constructor's interpreter_factory= API and default PythonInterpreter remain unchanged; context/global configuration still replaces the default when no call-time override is supplied.

Rename any RLM signature input named interpreter_factory. That name is now reserved for runtime configuration; declaring it as a signature input raises ValueError when constructing RLM.

This change applies to RLM only. CodeAct and ProgramOfThought retain their existing call-time APIs.

PR: #10493 by @isaacbmiller.

The Experimental 3.3 LM Types Are Replaced Now

The old dspy.LMRequest, dspy.LMResponse, and related experimental exports are removed. Importing dspy.core.types raises a migration error, and forward_contract="typed_lm" is rejected. These are replacements, not aliases:

Experimental 3.3 API	3.4 replacement
`dspy.LMRequest`, `dspy.LMResponse`	`dspy.lm15.Request`, `dspy.lm15.Response`
`dspy.LMMessage`, `dspy.LMConfig`	`dspy.lm15.Message`, `dspy.lm15.Config`
`dspy.System(text)`	`Request(system=text, ...)`
`dspy.User(text)`, `dspy.Assistant(text)`	`Message.user(text)`, `Message.assistant(text)`
`response.outputs[0].parts`	`response.message.parts`

The new types are frozen dataclasses rather than Pydantic models, with different validation and shapes. Old pickles containing removed experimental classes are not automatically migrated; load and export them in their original environment first. Ordinary provider-response cache compatibility is separate and remains supported.

experimental=True no longer makes ordinary prompt calls return typed responses. Use an explicit request:

import dspy
from dspy.lm15 import Config, Message, Request

lm = dspy.LM("azure/your-deployment")

# Before: OpenAI-style messages, with a list result (deprecated).
outputs = lm(messages=[{"role": "user", "content": "What is DSPy?"}])

# After: a typed request and response.
response = lm(Request(
    model=lm.model,
    system="Be concise.",
    messages=(Message.user("What is DSPy?"),),
    config=Config(max_tokens=200),
))
print(response.text)

Use your configured provider/deployment and credentials. An explicit request's model must match the LM; put generation options in Config, since LM generation defaults are not added. Config.cache controls provider-side prompt caching, not DSPy's response cache. DSPy's signature types—such as Image, Audio, File, Tool, ToolCalls, and History—and public LM error classes remain supported.

Legacy LM Interfaces Are Deprecated Until the 3.5 Cutoff

The following still execute in 3.4 but emit DeprecationWarning and are scheduled for removal in 3.5:

Public OpenAI-style lm(messages=[...]) calls, including SDK message objects. Use explicit requests as above.
Custom BaseLM.forward() and aforward() integrations. Implement the engine interface.
LegacyEngine, AsyncLegacyEngine, and custom complete_legacy() shortcuts. These are transition tools, not permanent escape hatches.

lm("hello") stays supported and list-returning in 3.5. Built-in adapters still use an internal dictionary/list boundary in 3.4; their canonical request/response migration is scheduled for 3.5. Custom adapters must not rely on the removed dspy.clients.openai_format module.

A minimal replacement for a custom legacy LM is:

import dspy
from dspy.lm15 import Message, Response, Usage


class EchoEngine:
    def complete(self, request):
        return Response(
            id=None,
            model=request.model,
            message=Message.assistant("hello"),
            finish_reason="stop",
            usage=Usage(),
        )


lm = dspy.LM("custom/echo", engine=EchoEngine())
print(lm("hello"))

Enable migration warnings during development with python -W default::DeprecationWarning your_program.py. See the 3.5 cutoff.

Engine Behavior, Costs, and Saved State

Native n answers use separate sequential requests, potentially billing input tokens more than once. Use engine="litellm" for that backend's native n behavior.
Custom engine objects own their connection. Put api_key, api_base, timeout, and related client settings on the engine itself; DSPy rejects them on LM construction, copying, and calls with custom engines. copy(engine=...) replaces the sync/async engine pair.
Custom engines need importable classes and JSON-compatible dump_state()/load_state() implementations to save and restore. Restoring them requires allow_unsafe_lm_state=True; only enable it for trusted state.
Native timeouts bound individual transport waits, not total generation time. An httpx.Timeout component set to None selects LiteLLM under auto or raises under forced lm15, rather than silently substituting a finite timeout.
A stream is not retried after emitting a chunk. Incomplete responses are not cached as successful results. Rate-limit errors preserve retry hints, request IDs, and rate-limit headers when available.
Typed LiteLLM streaming supports Chat Completions, not Responses. Native Responses supports streaming and early stop matching; closing early can lose final usage and does not guarantee provider generation or billing stops. Typed LiteLLM Responses applies stops after the full reply and retains reported usage.
Unknown cost remains unknown rather than zero. Provider adaptations are recorded in LM history. Native listener chunks need not be LiteLLM class instances.

Other Compatibility Notes

Pydantic 2.11.0 is the minimum supported version. The new optional typesafe extra requires typesafe-sdk>=0.6.0,<1.0.0; it is not added to the base installation.
ReActV2 output fields cannot be named history or termination_reason; rename those fields to avoid metadata collisions.
Calling an async tool synchronously inside a running event loop raises ValueError, even with async/sync conversion enabled. Use await tool.acall(...).
Synchronous streaming propagates producer failures instead of silently ending. streamify unwraps a single nested task-group failure; multiple failures remain grouped.
Evaluate rejects empty development sets with a descriptive ValueError.
Native strict schemas derived from Pydantic models now require all properties as OpenAI expects. Caller-supplied raw schemas are left unchanged.
Cache implementations load only when their tiers are enabled, allowing both tiers to be disabled without constructing filesystem-backed cache storage. Exact embedding retrieval shares the corpus table across queries; its FAISS path is unchanged.

Full PR List

Jev, Decision Types, and Calibration

Add experimental Noul, Choice, and Score types and the optional TypeSafe/Jev client by @isaacbmiller (#10463).
Add the experimental ReAnchor calibration optimizer for Predict by @isaacbmiller and @dbreunig (#10475).

Language Models and Engines

Vendor lm15 as a package subtree by @MaximeRivest (#10359).
Run LM execution through lm15 engines and retire the experimental 3.3 types by @MaximeRivest (#10366).
Preserve Retry-After across bundled lm15 async and auxiliary calls by @MaximeRivest (#10371).
Update bundled lm15 and integrate native timeouts, stop handling, and error diagnostics by @MaximeRivest (#10409).
Update bundled lm15 with declared-provider support by @MaximeRivest (#10440).
Enforce custom-engine connection ownership and explicit state serialization by @MaximeRivest (#10441).
Register HTTP providers with per-LM bindings and connection-preserving fallback by @MaximeRivest (#10442).
Fix streamify error propagation, dead-loop pools, strict schemas, and scoped cloudpickle registrations by @MaximeRivest (#10451).
Sync bundled lm15, preserve structured judgment outputs, and retain rate-limit evidence at DSPy's public boundary by @isaacbmiller (#10469).

Agents, Tools, and Interpreters

Reject reserved ReActV2 output names by @tjdharamsi (#9852).
Preserve output capture for single-line ProgramOfThought code by @chuenchen309 (#10050).
Reject synchronous async-tool calls inside running event loops by @isaacbmiller (#10146).
Add persistent LocalInterpreter by @isaacbmiller (#10238).
Recommend ReActV2 in optimizer-authored Flex guidance by @michaelisaac-dev (#10265).
Honor positive odd RLM truncation limits by @isaacbmiller (#10340).
Raise when ReActV2 cannot submit final outputs by @isaacbmiller (#10355).
Add async ReActV2 execution and MCP coverage by @isaacbmiller (#10356).
Propagate LocalInterpreter host-tool cancellation and interrupts by @isaacbmiller (#10379).
Allow global interpreter-factory configuration to replace the default PythonInterpreter by @adriaanm (#10383).
Replace RLM's live-interpreter call-time override with keyword-only interpreter_factory= and reserve that input name by @isaacbmiller (#10493).

Optimization, Evaluation, Retrieval, and Usage

Make Example hashing order-insensitive to match equality by @Kymi808 (#9858).
Preserve the input/label split when copying an Example by @iamsharduld (#9946).
Sample labeled demonstrations independently per BootstrapFewShot predictor by @iamsharduld (#9948).
Raise a descriptive error for empty evaluation sets by @roli-lpci (#9978).
Roll nested usage trackers into their parent on scope exit by @asparagus (#10065).
Add GEPA's custom Flex code_proposer hook by @dbreunig (#10212).
Keep GEPA trace-capture results aligned after program failures by @dbreunig (#10305).
Reduce exact embedding-retrieval memory use by sharing the corpus table across queries by @kiteretsu903 (#10398).

Adapters, Streaming, Imports, and Caching

Propagate synchronous streaming errors by @he-yufeng (#9864).
Use the correct base64 source type for PDF documents by @NishchayMahor (#9977).
Coerce non-string Literal members during parsing by @spjosyula (#10010).
Honor the remaining batch deadline in Unbatchify instead of resetting its timeout on each queue read by @chuenchen309 (#10038).
Quote only string Literal members in BAMLAdapter schemas by @nikolauspschuetz (#10074).
Defer AnyIO, OpenAI, and jiter imports to their use sites by @adriaanm (#10381).
Allow disabled cache tiers without constructing their backends by @adriaanm (#10382).
Drop tool_choice when no tools are sent to the LM by @NithilanVishvanath (#10399).

Documentation

Correct the documented ReAct max_iters default by @ellacroix (#10013).
Explain GEPA training/validation roles and dataset splits by @ymxlx (#10048).
Update homepage release status by @isaacbmiller (#10274).
Add Mike versioning and historical documentation snapshots by @isaacbmiller (#10315).
Migrate Current documentation to native Zensical by @isaacbmiller (#10316).
Automate Current updates and post-publication release snapshots by @isaacbmiller (#10317).
Remove one-time documentation migration scaffolding and legacy publication paths by @isaacbmiller (#10332).
Correct CodeAct's stale constructor docstring by @simpleqt (#10351).
Pin historical release badges by @isaacbmiller (#10413).
Add a maintainer-guided release-notes skill by @isaacbmiller (#10414).
Reposition the version picker in the header by @isaacbmiller (#10418).
Polish the version picker and repository metadata by @isaacbmiller (#10421).
Align the version picker with search by @isaacbmiller (#10438).
Serve versioned documentation from the static root by @isaacbmiller (#10447).
Preserve versioned documentation trailing slashes by @isaacbmiller (#10448).

Dependencies, CI, and Release Engineering

Update main's version metadata for 3.3.1 by @github-actions (#10260).
Require Pydantic 2.11 by @isaacbmiller (#10271).
Update denoland/setup-deno from 2.0.4 to 2.0.5 by @dependabot (#10288).
Update astral-sh/setup-uv from 8.2.0 to 10.0.1 by @dependabot (#10289).
Update pypa/gh-action-pypi-publish from 1.14.0 to 1.14.2 by @dependabot (#10290).
Update actions/setup-python from 6.2.0 to 7.0.0 by @dependabot (#10291).
Update locked orjson from 3.11.9 to 3.12.0 by @dependabot (#10292).
Update zizmor-action from 0.5.7 to 0.6.2 by @dependabot (#10293).
Update locked json-repair from 0.63.0 to 0.63.3 by @dependabot (#10295).
Update documentation Mistune from 3.2.1 to 3.3.4 by @dependabot (#10298).
Update zizmor-action from 0.6.2 to 0.6.3 by @dependabot (#10369).
Install pytest-mock in release test environments by @isaacbmiller (#10384).
Update main's version metadata for 3.4.0b1 by @github-actions (#10385).
Install uv for documentation bootstrap by @isaacbmiller (#10403).
Stabilize the local-interpreter timeout test by @isaacbmiller (#10404).
Keep documentation bootstrap reviewable and version-correct by @isaacbmiller (#10405).
Skip alias-collision testing when symlink creation is unavailable by @iam-kira (#10410).

Contributors

Thank you to @adriaanm, @asparagus, @chuenchen309, @dbreunig, @ellacroix, @he-yufeng, @iam-kira, @iamsharduld, @isaacbmiller, @kiteretsu903, @Kymi808, @MaximeRivest, @michaelisaac-dev, @nikolauspschuetz, @NishchayMahor, @NithilanVishvanath, @roli-lpci, @simpleqt, @spjosyula, @tjdharamsi, and @ymxlx.

Automation contributions were made by @dependabot and @github-actions.

Full Changelog: 3.3.1...3.4.0

3.4.0b111 Sept 2026pre-releaseDeprecated

Use engine="lm15" to require native execution and reject unsupported mappings. LiteLLM remains installed and supported; it is not deprecated.

DSPy 3.4.0 Beta 1

DSPy 3.4.0b1 is the first beta of 3.4. It moves language-model execution to a shared engine interface, adds a local CPython interpreter for trusted code, and brings async execution to ReActV2. It also adds custom Flex code proposals in GEPA and fixes evaluation, streaming, and demonstration-sampling bugs.

This is a prerelease, not the stable 3.4.0 release. APIs and behavior may change before stable. We especially welcome feedback on native versus LiteLLM compatibility, tool calling and streaming, custom LM migration, saved programs, and multi-answer latency and costs. Please include your engine selection and a minimal reproduction when reporting issues.

Install this beta explicitly:

pip install --upgrade "dspy==3.4.0b1"

3.4 is the LM transition release; 3.5 is the migration deadline. Ordinary DSPy programs and list-returning prompt calls remain supported, but the experimental LM types introduced in 3.3 are replaced in this release. Review the compatibility notes if you use those types, implement a custom LM, pass OpenAI-style messages directly to an LM, or request multiple answers with n.

Highlights

Native LM Engines and a New Custom-Backend Interface — @MaximeRivest

DSPy's LM layer now uses the lm15 request, response, and streaming types bundled with DSPy. Import them from dspy.lm15; no separate lm15 installation is needed.

The default engine="auto" prefers native lm15 execution for supported routes and representable inputs. Unsupported routes, client settings, and ordinary provider-specific inputs that cannot be represented faithfully select LiteLLM before execution. Authentication failures, timeouts, and provider errors do not trigger a switch to another backend.

import dspy

# Prefer native execution where supported; select compatibility where needed.
lm = dspy.LM("openai/gpt-4o-mini")

# Explicitly retain the LiteLLM compatibility backend.
compat_lm = dspy.LM("openai/gpt-4o-mini", engine="litellm")

Use engine="lm15" to require native execution and reject unsupported mappings. LiteLLM remains installed and supported; it is not deprecated.

Custom backends can now implement complete(Request) -> Response instead of subclassing BaseLM and returning provider-shaped objects:

from dspy.lm15 import Message, Response, Usage

class EchoEngine:
    def complete(self, request):
        return Response(
            id=None,
            model=request.model,
            message=Message.assistant("hello"),
            finish_reason="stop",
            usage=Usage(),
        )

lm = dspy.LM("custom/echo", engine=EchoEngine())

Supply async_engine= for async calls and implement canonical streaming events when needed. DSPy owns response caching, managed retries, callbacks, history, and usage accounting. Custom engines are caller-owned and are not closed by DSPy.

Ordinary calls retain their existing cache-key format and can read existing SDK-response cache entries. New native cache entries contain plain serialized data and support restricted deserialization; explicit typed requests use a separate cache namespace. Existing dspy.streamify listeners remain supported.

See the LM migration guide and custom-engine tutorial.

PRs: #10359, #10366, #10371

LocalInterpreter: Persistent CPython for Trusted Code — @isaacbmiller

dspy.LocalInterpreter runs generated Python in a persistent local CPython subprocess, using the current Python executable. It provides ordinary Python compatibility without Deno, while separating the worker's memory, stdout, and lifecycle from the DSPy process.

rlm = dspy.RLM(
    "question: str -> answer: int",
    interpreter_factory=dspy.LocalInterpreter,
)

State and imports persist within an interpreter session. LocalInterpreter supports JSON-compatible inputs and tool results, sync and async host tools, typed SUBMIT, interpreter callbacks, and execution timeouts. It works with both RLM and Flex. The usual factory lifecycle still creates a fresh interpreter for each module invocation.

LocalInterpreter is not a security sandbox. Generated code retains the host user's filesystem, environment, credentials, subprocess, and network access. Use the default PythonInterpreter or a remote sandbox for untrusted code; the default has not changed.

execution_timeout includes host-tool time and terminates the worker when exceeded. It cannot forcibly stop a running host callable; that callable may finish later, but its result is discarded. Guest threads must finish before an execution returns, or the interpreter session becomes terminal.

Host-tool cancellation and interrupts propagate to the caller and shut down the stranded worker, including when no execution timeout is configured. They no longer leave execution waiting indefinitely for a worker reply. Ordinary tool errors remain recoverable.

PRs: #10238, #10379

Async ReActV2 and Explicit Final-Output Failures — @isaacbmiller

The experimental dspy.ReActV2 now supports await agent.acall(...), including async prediction, async tools, and forced final submission. This enables async MCP tools to run through the agent's structured tool-call history, preserving call IDs and tool results across turns.

Tools execute sequentially on the async path. This does not add parallel tool execution or automatically offload blocking synchronous tools.

ReActV2 also no longer returns an incomplete Prediction when final submission fails. Missing or invalid submission raises ValueError; parse and context-window failures from the forced submission propagate. Successful predictions continue to include declared outputs, history, and a termination reason.

The MCP guide includes an async ReActV2 client/server example.

PRs: #10355, #10356

Custom Flex Code Proposals and More Reliable GEPA Evaluation — @dbreunig

dspy.GEPA now accepts code_proposer=, complementing instruction_proposer=. Custom proposers receive the selected Flex code components, candidate source, reflective examples, task descriptions, and context blurbs, and return replacement module source for each component.

This lets applications customize code-generation constraints and domain guidance without monkeypatching the built-in proposer. The built-in proposer remains the default, and programs without Flex components are unaffected.

GEPA's trace-capture evaluation also keeps outputs and scores aligned with the input batch when a program crashes on an example. Failed examples receive failure_score rather than disappearing and causing an indexing error or shifting later results. This addresses the missing/misaligned validation-results issue noted in the 3.3.1 release; it does not require an upstream GEPA upgrade.

PRs: #10212, #10305

API and Compatibility Changes

The Experimental 3.3 LM Types Are Replaced Now

Experimental 3.3 API	3.4 replacement
`dspy.LMRequest`, `dspy.LMResponse`	`dspy.lm15.Request`, `dspy.lm15.Response`
`dspy.LMMessage`, `dspy.LMConfig`	`dspy.lm15.Message`, `dspy.lm15.Config`
`dspy.System(text)`	`Request(system=text, ...)`
`dspy.User(text)`, `dspy.Assistant(text)`	`Message.user(text)`, `Message.assistant(text)`
`response.outputs[0].parts`	`response.message.parts`

The new types are frozen dataclasses, not Pydantic models, and their validation and data shapes differ. Old pickles containing removed experimental classes are not automatically migrated; load and export them in their original environment first. Ordinary provider-response caches are a separate compatibility path and remain readable.

experimental=True no longer changes ordinary LM calls into typed responses. Ordinary prompt calls return lists; explicit requests return a Response:

from dspy.lm15 import Config, Message, Request

lm = dspy.LM("openai/gpt-4o-mini")
response = lm(Request(
    model=lm.model,
    system="Be concise.",
    messages=(Message.user("What is DSPy?"),),
    config=Config(max_tokens=200),
))
print(response.text)

An explicit request's model must match the LM. Set generation options in its Config; LM generation defaults are not added. Config.cache controls provider-side prompt caching, not DSPy's response cache.

DSPy's signature types, including Image, Audio, File, Tool, ToolCalls, and History, are not removed. Existing public DSPy LM error classes remain supported.

Legacy LM Integrations Are Deprecated for Removal in 3.5

The following still execute in 3.4 but emit DeprecationWarning:

Public OpenAI-style lm(messages=[...]) calls, including provider SDK message objects. Migrate to explicit lm15 requests.
Custom BaseLM.forward() and aforward() integrations. Migrate to the engine interface.
LegacyEngine, AsyncLegacyEngine, and custom complete_legacy() shortcuts. These are transition tools, not permanent compatibility interfaces.

lm("hello") remains a list-returning convenience in 3.5. Built-in adapters still use an internal dictionary/list boundary in 3.4; their canonical request/response migration is scheduled for 3.5. Custom adapters must not depend on the removed dspy.clients.openai_format module.

To reveal deprecation warnings during development:

python -W default::DeprecationWarning your_program.py

Native Multi-Answer Calls, Retries, and Streaming

Native n answers use separate sequential requests. This can increase latency and bill input tokens more than once compared with a provider-native multi-answer request. Choose engine="litellm" to retain that backend's native n behavior.
DSPy owns managed retries and honors valid provider retry hints. A stream is not retried after a chunk has been emitted, and incomplete responses are not cached as successful results.
Native cost estimates remain unknown when reliable pricing is unavailable; unknown cost is not reported as zero.
Typed LiteLLM streaming currently supports Chat Completions only. Native Responses streaming is supported.
Native listener-facing chunks need not be LiteLLM class instances. Custom chunk consumers should not rely on that identity.

PRs for the LM changes above: #10366, #10371

Other Compatibility Changes

Pydantic 2.11.0 is now the minimum supported version. #10271
ReActV2 rejects signatures with output fields named history or termination_reason, which collide with its prediction metadata. Rename those outputs. #9852
Calling an async tool synchronously from a running event loop raises a descriptive ValueError, even with allow_tool_async_sync_conversion enabled. Use await tool.acall(...). #10146
Synchronous streaming now propagates producer failures to the consumer instead of silently ending. #9864
Evaluate rejects an empty development set with a descriptive ValueError instead of failing with ZeroDivisionError. #9978

Full PR List

Language Models and Engines

Vendor lm15 as a package subtree by @MaximeRivest (#10359).
Run LM execution through lm15 engines and retire the experimental 3.3 types by @MaximeRivest (#10366).
Preserve Retry-After across bundled lm15 async and auxiliary calls by @MaximeRivest (#10371).

Agents, Tools, and Interpreters

Reject reserved ReActV2 output names by @tjdharamsi (#9852).
Preserve output capture for single-line ProgramOfThought code by @chuenchen309 (#10050).
Reject synchronous async-tool calls inside running event loops by @isaacbmiller (#10146).
Add persistent LocalInterpreter by @isaacbmiller (#10238).
Recommend ReActV2 in optimizer-authored Flex module guidance by @michaelisaac-dev (#10265).
Honor positive odd RLM truncation limits by @isaacbmiller (#10340).
Raise when ReActV2 cannot submit final outputs by @isaacbmiller (#10355).
Add async ReActV2 execution and MCP end-to-end coverage by @isaacbmiller (#10356).
Propagate LocalInterpreter host-tool cancellation and interrupts instead of hanging by @isaacbmiller (#10379).

Optimization, Evaluation, and Examples

Make Example hashing order-insensitive to match equality by @Kymi808 (#9858).
Preserve the input/label split when copying an Example by @iamsharduld (#9946).
Sample labeled demonstrations independently from the full available pool for each BootstrapFewShot predictor by @iamsharduld (#9948).
Raise a descriptive error for empty evaluation sets by @roli-lpci (#9978).
Add GEPA's custom Flex code_proposer hook by @dbreunig (#10212).
Keep GEPA trace-capture results aligned after program failures by @dbreunig (#10305).

Adapters, Streaming, and Batching

Propagate synchronous streaming errors by @he-yufeng (#9864).
Use the correct base64 source type for PDF documents by @NishchayMahor (#9977).
Coerce non-string Literal members during parsing by @spjosyula (#10010).
Honor the remaining batch deadline in Unbatchify instead of resetting the full timeout on every queue read by @chuenchen309 (#10038).
Quote only string Literal members in BAMLAdapter schemas by @nikolauspschuetz (#10074).

Documentation

Correct the documented ReAct max_iters default by @ellacroix (#10013).
Explain GEPA training/validation roles and dataset-split guidance by @ymxlx (#10048).
Update homepage release status by @isaacbmiller (#10274).

Dependencies, CI, and Release Engineering

Update main's version metadata for 3.3.1 by @github-actions (#10260).
Require Pydantic 2.11 by @isaacbmiller (#10271).
Update denoland/setup-deno from 2.0.4 to 2.0.5 by @dependabot (#10288).
Update astral-sh/setup-uv from 8.2.0 to 10.0.1 by @dependabot (#10289).
Update pypa/gh-action-pypi-publish from 1.14.0 to 1.14.2 by @dependabot (#10290).
Update actions/setup-python from 6.2.0 to 7.0.0 by @dependabot (#10291).
Update locked orjson from 3.11.9 to 3.12.0 by @dependabot (#10292).
Update zizmorcore/zizmor-action from 0.5.7 to 0.6.2 by @dependabot (#10293).
Update locked json-repair from 0.63.0 to 0.63.3 by @dependabot (#10295).
Update documentation Mistune from 3.2.1 to 3.3.4 by @dependabot (#10298).

Contributors

Thank you to @chuenchen309, @dbreunig, @ellacroix, @he-yufeng, @iamsharduld, @isaacbmiller, @Kymi808, @MaximeRivest, @michaelisaac-dev, @nikolauspschuetz, @NishchayMahor, @roli-lpci, @spjosyula, @tjdharamsi, and @ymxlx for contributing to this release.

Automation contributions were made by @dependabot and @github-actions.

Full Changelog: 3.3.1...3.4.0b1

Open source →

3.3.121 Aug 2026Deprecated

CodeAct and ProgramOfThought Deprecation

DSPy 3.3.1

DSPy 3.3.1 contains many interpreter fixes and improvements. It makes PythonInterpreter
easier to install, substantially strengthens sandbox isolation and request
handling, and adds end-to-end visibility into interpreter execution. The release
also improves optimizer throughput, adapter correctness, and MCP compatibility.

Highlights

PythonInterpreter: Managed Runtime, Hardening, and Lifecycle Visibility

Installation, isolation, and execution integrity

PythonInterpreter now has an optional managed runtime installation:

pip install "dspy[deno]"

DSPy prefers that managed binary when present, while continuing to support
system Deno 2.x and an explicit custom deno_command. The default path pins
Pyodide, validates Deno >=2.0.0,<3.0.0, and ignores ambient Node and Deno
project configuration so nearby application files cannot change sandbox startup.

The interpreter also closes several execution-integrity and isolation gaps:

unsolicited sandbox diagnostics can no longer desynchronize JSON-RPC replies;
request IDs are unpredictable, and recursive execution through one of an
interpreter's own host tools is rejected;
bundled runtime files are protected and Deno-cache access is revoked after
startup;
mounted files with distinct host paths cannot silently collide at the same
sandbox basename; and
guest code cannot change host-tool identity by mutating JavaScript globals or
prototypes.

Observability and agent integration

DSPy's callback API now exposes the complete interpreter lifecycle:

interpreter execution start and end;
sandbox-to-host tool-call start and end;
interpreter process startup and shutdown.

Events retain callback ancestry across modules, interpreters, tools, and LM
calls. End callbacks receive terminating BaseException values such as
cancellation and interruption instead of incorrectly reporting those operations
as successful. Optimizer compile() runs receive the same start/end coverage.

PythonInterpreter.execution_instructions now gives RLM an accurate description
of the Pyodide environment, including state persistence and unavailable native
process capabilities. This helps generated code use the sandbox correctly.

Typing, serialization, and compatibility details

Tool defaults and NoneType annotations serialize correctly across the
sandbox boundary.
CodeInterpreterError is now a DSPyError while retaining its existing
RuntimeError compatibility.
LM-facing execution errors use one consistent formatter across interpreter and
agent modules.
Existing system Deno and custom-command integrations remain supported; the
managed runtime is opt-in.

PRs: #10119,
#10120,
#10134,
#10135,
#10136,
#10186,
#10190,
#10194,
#10205,
#10206,
#10208, and
#10255

Faster Multi-Proposal GEPA Optimization

DSPy now uses GEPA 0.1.4 and supports its multi-proposal sampling, selection,
acceptance, tracking, and checkpoint-state contracts through gepa_kwargs.
DSPy's adapter saves and restores its random-number-generator state, making
resumed proposal sampling consistent with uninterrupted optimization.

When a sampling strategy produces multiple candidates, DSPy can evaluate those
candidates concurrently. Candidate-level and example-level concurrency share the
existing num_threads budget rather than multiplying it. For example, four
candidates evaluated with num_threads=8 receive two example workers each; total
DSPy-controlled concurrency remains eight.

import dspy
from gepa.strategies.proposal_sampling import IndependentSampling
from gepa.strategies.proposal_selection import BestImprovement

optimizer = dspy.GEPA(
    metric=metric,
    max_metric_calls=2_000,
    reflection_lm=dspy.LM("openai/gpt-5", temperature=1.0, max_tokens=32_000),
    num_threads=8,
    gepa_kwargs={
        "sampling_strategy": IndependentSampling(4),
        "selection_strategy": BestImprovement(),
        "acceptance_criterion": "strict_improvement",
    },
)

The default single-proposal strategy retains its previous execution shape.
max_reflection_cost is not yet supported by DSPy's GEPA adapter and now raises
clearly when set instead of silently providing an ineffective budget.

Metrics can also report named objective_scores and select an objective-aware
frontier through gepa_kwargs. Objective, hybrid, and cartesian frontiers let
GEPA use dimensions such as quality, privacy, or cost when selecting parents and
merges, while the scalar metric continues to gate acceptance and select the final
program. Tracked results expose aggregate objective scores, best candidates per
objective, and each objective's independently achieved maximum.

GEPA 0.1.4 has a known upstream limitation: it requests traces while evaluating
accepted candidates on the full validation set. For programs whose traced and
ordinary evaluation paths differ after a runtime failure, this can cause missing
or misaligned validation results. The upstream correction is targeted for GEPA
0.1.5.

PRs: #10209,
#10210,
#10259

More Reliable Structured Adapter Outputs

When an LM omits an output field with a declared default, default factory, or
None-allowing annotation, ChatAdapter, JSONAdapter, XMLAdapter, and adapters
built on them now apply the declared fallback. Missing required outputs continue
to raise AdapterParseError.

This also prevents adapter fallback merely because a provider omitted a native
optional output.

XMLAdapter now formats and parses nested Pydantic models, typed dictionaries,
lists, mappings, nullable fields, and unions as nested XML. It continues to
accept the previous JSON-inside-an-outer-XML-field representation for backward
compatibility.

PRs: #10148,
#10239

MCP SDK v2 Compatibility and Structured Results

DSPy's MCP bridge supports both MCP SDK v1 and v2 field names, v1
ClientSession, and the v2 high-level Client. The default tool-result semantics
are unchanged: historical text and non-text content remains authoritative rather
than being replaced by v2 structured content.

Applications can now opt into machine-readable MCP results:

tool = dspy.Tool.from_mcp_tool(client, mcp_tool, result_mode="structured")

Structured mode returns structuredContent exactly when the server supplies it,
including arrays, scalar values, empty values, and explicit JSON null. It falls
back to the existing content conversion when structured content is absent. DSPy
does not infer, parse, or unwrap the returned value.

PRs: #10188,
#10235

API and Compatibility Changes

CodeAct and ProgramOfThought Deprecation

dspy.CodeAct and dspy.ProgramOfThought now emit DeprecationWarning when
constructed. They are scheduled for removal in DSPy 3.5; use dspy.RLM for new
code.

PR: #10198

Resource Download Timeouts

Image.from_url() and Audio.from_url() now default to a 30-second request
timeout instead of potentially waiting forever:

image = dspy.Image.from_url(url, timeout=60)
audio = dspy.Audio.from_url(url, timeout=60)

Pass timeout=None to retain the previous unbounded behavior.

PR: #10149

Typed Interpreter and ReAct Errors

CodeInterpreterError is now also a DSPyError while retaining
RuntimeError compatibility. ReAct preserves ContextWindowExceededError after
trajectory truncation is exhausted, and LM-facing execution errors now use one
consistent formatter.

PRs: #10134,
#10132,
#10135,
#10139

Additional Fixes

ParallelExecutor correctly treats a completed task returning None as
complete. #10142
COPRO.compile(..., eval_kwargs=None) now matches its documented optional
contract. #10087
Dataset.reset_seeds() now honors valid zero-valued sizes and seeds.
#9906

Full PR List

GEPA and Optimizers

Upgrade DSPy's GEPA engine to 0.1.4 by @isaacbmiller
(#10209).
Parallelize GEPA candidate evaluation within the existing thread budget by
@isaacbmiller (#10210).
Add objective-aware GEPA frontier tracking and result metadata by @isaacbmiller
(#10259).
Make COPRO.compile's eval_kwargs optional by @katherineahn
(#10087).

Callbacks and Parallel Execution

Expose interpreter lifecycle callback events by @isaacbmiller
(#10119).
Expose optimizer compile callback events by @isaacbmiller
(#10120).
Report terminating BaseException values to callback end handlers by
@isaacbmiller (#10194).
Track completed None results in ParallelExecutor by @isaacbmiller
(#10142).

Adapters, Tools, and MCP

Apply defaults and nullable fallbacks for omitted optional output fields by
@michaelisaac-dev (#10148).
Add default timeouts to explicit image and audio URL downloads by @immu4989
(#10149).
Support MCP SDK v2 without changing tool-result semantics by @isaacbmiller
(#10188).
Add opt-in structured MCP tool results by @isaacbmiller
(#10235).
Format and parse nested structured data with XMLAdapter by @isaacbmiller
(#10239).

Agents, Errors, and Code Execution

Preserve typed ReAct context-window errors by @isaacbmiller
(#10132).
Root CodeInterpreterError under DSPyError while retaining
RuntimeError compatibility by @isaacbmiller
(#10134).
Share LM-facing exception formatting across modules by @isaacbmiller
(#10135).
Add interpreter execution instructions to RLM prompts by @isaacbmiller
(#10136).
Repair ReAct's formatter after parallel merges by @isaacbmiller
(#10139).
Add managed Deno support and isolate interpreter dependencies by @isaacbmiller
(#10186).
Prevent unhandled sandbox rejections from desynchronizing interpreter requests
by @michaelisaac-dev
(#10190).
Deprecate CodeAct and ProgramOfThought in favor of RLM by @isaacbmiller
(#10198).
Reject colliding interpreter file mounts by @isaacbmiller
(#10205).
Isolate the interpreter's Deno cache and runtime files by @isaacbmiller
(#10206).
Harden interpreter request handling and tool wrappers by @isaacbmiller
(#10208).
Scope Python standard-library guidance to PythonInterpreter-backed RLMs by
@isaacbmiller (#10255).

Datasets

Honor zero-valued sizes and seeds in Dataset.reset_seeds by @alvinttang
(#9906).

Documentation

Fix four dead external documentation links by @yzxcj797
(#10213).
Add the Nubank DSPy case study by @isaacbmiller
(#10228).
Document the ReActV2 transition, structured history, and tool interfaces by
@isaacbmiller (#10229).
Update the MCP tutorial to use the SDK v2 high-level Client by @isaacbmiller
(#10249).
Repair the BetterTogether optimizer-overview link by @saime428
(#10253).

Testing, CI, Dependencies, and Release Engineering

Update main's version metadata after the 3.3.0 release
(#10127).
Repair dead settings ownership assertions by @isaacbmiller
(#10131).
Cap FastAPI for LiteLLM proxy compatibility in the development environment by
@daleselaji-dev (#10151).
Reuse one LiteLLM test server per pytest worker by @isaacbmiller
(#10154).
Use a memory-only cache by default in tests by @isaacbmiller
(#10156).
Remove wall-clock retry waits from tests by @isaacbmiller
(#10157).
Run extra test suites in parallel by @isaacbmiller
(#10164).
Prefetch the Ollama image during test setup by @isaacbmiller
(#10169).
Regenerate the project lockfile by @isaacbmiller
(#10199).
Update the documentation build's urllib3 dependency
(#9931).
Update GitHub Actions checkout
(#9945).
Update GitHub Actions Python setup
(#9965).
Update GitHub Actions caching
(#9966).
Update the zizmor security-analysis action
(#9967).
Update the documentation build's mkdocstrings-python dependency
(#9968).
Update the actionlint workflow action
(#9988).
Update the documentation build's Mistune dependency
(#10109).
Update the documentation build's MkDocs Material dependency
(#10110).

Contributors

Thank you to @alvinttang, @daleselaji-dev, @immu4989, @isaacbmiller,
@katherineahn, @michaelisaac-dev, @saime428, and @yzxcj797 for contributing to
this release.

Full Changelog: 3.3.0...3.3.1

Open source →

3.3.03 Aug 2026Deprecated

Pydantic payloads containing download or verify are rejected without fetching. The deprecated direct developer call Image(url, download=True) remains…

DSPy 3.3.0

DSPy 3.3.0 is a feature release with a new experimental way to optimize programs as code, a native-tool-aware ReAct implementation, and the next stage of DSPy's move toward a typed, provider-neutral language-model system.

Most existing DSPy programs should keep working without changes. Review the API changes if you construct Image, Audio, or File values from paths or URLs; use NumPy-backed features from the base install; inspect detailed GEPA results; construct code interpreters directly; use RLM(max_iterations=...); consume raw Responses API tool-call outputs; or catch provider-specific LM exceptions.

We would especially appreciate feedback on Flex, ReActV2, and the typed LM path. These APIs expand what DSPy can optimize and how it can connect to model providers, and real-world usage will help shape their next iterations.

Highlights

Flex Optimizes Program Structure, Not Just Prompts — @michaelisaac-dev

Most DSPy modules fix the shape of a program up front: Predict makes one prediction, ReAct runs a tool loop, and RLM runs a code interpreter in a loop. Optimizers can improve the instructions around that structure, but the structure itself stays fixed. The new experimental dspy.Flex moves the implementation into the search space so GEPA can discover the decomposition instead.

Give Flex the same signature you would give Predict and it starts with the simplest working baseline: one dspy.Predict, or one dspy.RLM when tools are supplied. During compilation, GEPA can rewrite the complete module implementation—changing the predictors, control flow, DSPy primitives, and balance between Python and LM calls—against your metric.

program = dspy.Flex("question -> answer")
optimized = dspy.GEPA(metric=metric, reflection_lm=reflection_lm).compile(
    program,
    trainset=trainset,
    valset=valset,
)

print(optimized.module_src)

Optimizer-authored source always runs in a CodeInterpreter sandbox, using dspy.PythonInterpreter by default. Predictor construction and LM calls bridge back to the host, broken candidates score as failures instead of crashing the search, and max_predictor_calls guards against runaway generated programs. Metrics can also accept a program_trace to score how a result was produced—for example, penalizing programs that make too many LM calls.

The optimized module_src is part of the program's serialized state, so saving and loading preserves the implementation GEPA discovered. Flex is experimental, and ordinary GEPA behavior is unchanged when a program does not contain a Flex module.

PR: #10047

ReActV2 and Native Tool-Calling History - @isaacbmiller

dspy.ReActV2 is a new version of ReAct built around native tool calling. It is currently marked as experimental.

The signature now uses dspy.History, dspy.Tool, and dspy.ToolCalls(which can now optionally store dspy.ToolCallResults), rather than the custom next_tool_args and custom trajectory syntax. Using dspy.History also means that messages are now broken up into user/assistant/tool groups rather than one long user message with the trajectory.

This changes the execution model in a few concrete ways:

parallel_tool_calls support: DSPy preserves each call/result pair by ID. You can do this in native mode or in non-native mode
Multi-turn native tool call support: Prior tool calls and results can be replayed as assistant and tool messages instead of being flattened into prompt text.
Each turn lives in dspy.History as structured messages rather than one ever-growing trajectory string, so providers with prompt caching can reuse stable prefixes more effectively. We have seen up to 50% decreases in cost for some tasks when testing this internally.

ReActV2 converts callables to dspy.Tool, adds an internal submit tool for final outputs, handles unknown tools and tool exceptions, accepts serialized history input, and can force final submission when the model does not call submit.

PRs: #9823, #9824, #9825, #9835

Typed, Provider-Neutral LM Boundary - @MaximeRivest

DSPy is moving from an untyped LM boundary based on prompt, messages, and provider-shaped kwargs toward a typed, provider-neutral contract:

def forward(self, request: dspy.LMRequest) -> dspy.LMResponse:
    ...

The resulting API is a cleaner LM extension point:

LiteLLM can become an optional compatibility fallback in the planned 3.5+ path, instead of a required part of the core LM contract.
Custom LM authors can implement one typed LMRequest -> LMResponse path instead of guessing which OpenAI/LiteLLM-shaped inputs will arrive.
Custom LMs can translate between DSPy's typed objects and their own provider, local runtime, gateway, or inference stack.
Adapters can start to depend on DSPy's representation of messages, multimodal content, tool calls, reasoning, citations, usage, cache controls, metadata, and stream events.

Most users do not need to change anything in 3.3. Existing lm(...), modules, and programs keep their current behavior by default.

Try out the typed return path with dspy.context(experimental=True), and the public migration plan explains the staged transition for custom LM and adapter authors.

See the full plan here

PRs: #9786, #9802, #9828

BaseLM Runtime, Save/Load, Errors, and LiteLLM Decoupling - @MaximeRivest

BaseLM now owns shared runtime state and supports sanitized state serialization through dump_state() and load_state(). Serialized LM state excludes API keys, preserves legacy saved states, and requires explicit opt-in before importing trusted custom LM classes.

Saved programs with custom LMs are easier to reason about, LM copies isolate DSPy-owned mutable state, and callers can catch dspy.LMError or a narrower DSPy subclass instead of depending on provider-specific exception classes. LiteLLM imports are lazy, which keeps the core LM API less coupled to a specific provider bridge at import time.

PRs: #9752, #9820, #9821, #9826

LM and Responses API Updates Since 3.3.0b1 - @MaximeRivest, @isaacbmiller

Since the beta, DSPy has added an explicit BaseLM.forward() contract, exported the typed LM API, supported typed direct calls through BaseLM.__call__, made optional-provider imports thread-safe, and fixed LM state round trips for GPT-5 models.

The OpenAI Responses path now emits Responses-native tool and tool_choice request shapes. Legacy Responses outputs use the same Chat-style tool-call representation as the Chat Completions path, while typed LMToolCallPart objects preserve raw provider fields.

PRs: #9837, #9840, #9841, #9843, #9877, #9999, #10003, #10014, #10026, #10028

API Changes

Breaking Changes

Resource Construction and Validation No Longer Perform Implicit I/O

Constructing or validating dspy.Image, dspy.Audio, and dspy.File values no longer interprets locator-shaped strings as instructions to read a local file or fetch a remote URL. This prevents LM-output parsing, Pydantic validation, and deserialization from silently granting filesystem or network access merely because a value resembles a path or URL.

Resource loading now requires an explicit factory:

Before 3.3	DSPy 3.3	Behavior
`Image(path)` or `Image(url=path)`	`Image.from_path(path)`	Read and embed a local image
`Image(url, download=True)`	`Image.from_url(url)`	Download and embed a remote image
`Image.from_url(url)` or `Image.from_url(url, download=False)`	`Image(url)` or `Image(url=url)`	Keep a non-downloading provider-fetched URL reference
`Audio(path)`	`Audio.from_path(path)`	Read and embed local audio
`Audio(url)`	`Audio.from_url(url)`	Download and embed remote audio
`File(path)`	`File.from_path(path)`	Read and embed a local file
`encode_image(path)`	`Image.from_path(path)`	Explicitly read a local image
`encode_audio(path_or_url)`	`Audio.from_path(path)` or `Audio.from_url(url)`	Explicitly load audio
`encode_file_to_dict(path)`	`File.from_path(path)`	Explicitly read a local file

There are several related compatibility changes:

Image.from_url() now downloads the resource and returns an embedded data URI. Use Image(url) when the model provider should fetch the reference instead.
Image.from_url(..., download=...) and the download_images / verify options on encode_image() were removed. Choose reference construction or an explicit factory instead.
Pydantic payloads containing download or verify are rejected without fetching. The deprecated direct developer call Image(url, download=True) remains available with a warning through 3.3.
The deprecated compatibility call requires a positional source: Image(url, download=True). Validation-style calls such as Image(url=url, download=True) are rejected.
Image.from_file(), Image.from_PIL(), and Audio.from_file() remain as deprecated aliases through 3.3 and are scheduled for removal in 3.4. Use Image.from_path(), Image(pil_image), and Audio.from_path() respectively.
Safe in-memory inputs—including data URIs, bytes, PIL images, audio arrays, structured dictionaries, and existing resource instances—remain supported.

The explicit Image.from_url(url, verify=...) and Audio.from_url(url, verify=...) factories still accept TLS certificate verification controls. The removed verify option applies to encode_image().

Image.from_url() and Audio.from_url() make synchronous caller-initiated requests, follow redirects, and do not provide an SSRF allowlist. Applications remain responsible for validating or allowlisting destinations derived from untrusted input.

PR: #10111 by @isaacbmiller

`numpy` Is Now Optional

numpy is no longer installed with base dspy. Features that need NumPy now require the numpy extra:

pip install "dspy[numpy]"

Affected areas include embeddings, KNN/KNNFewShot, SIMBA, and other NumPy-backed optimizer or retrieval paths. (#9659 by @isaacbmiller)

GEPA Result Shapes Changed With `gepa[dspy]==0.1.1`

The upstream GEPA 0.1.1 API changed several result structures, and DspyGEPAResult now mirrors those shapes. Users who inspect optimized_program.detailed_results may need to update code:

DspyGEPAResult.candidates is now a list of compiled DSPy modules, not instruction dictionaries.
DspyGEPAResult.best_candidate now returns a compiled DSPy module.
val_subscores is now list[dict[Any, float]], keyed by validation instance id.
per_val_instance_best_candidates is now dict[Any, set[int]].
best_outputs_valset is now dict[Any, list[tuple[int, Prediction]]] when tracked.
highest_score_achieved_per_val_task now returns a dictionary keyed by validation instance id.

If you pass custom GEPA reflection templates directly, note that GEPA 0.1.1 renamed default placeholders from <curr_instructions> / <inputs_outputs_feedback> to <curr_param> / <side_info>. In dspy.GEPA, passing reflection_prompt_template through gepa_kwargs now raises a clear ValueError; use instruction_proposer for custom proposal behavior instead. (#9673 by @BenMcH)

`RLM.max_iterations` Is Now `RLM.max_iters`

The RLM constructor now uses the same max_iters name as other iterative DSPy modules:

# Before
rlm = dspy.RLM("context, query -> answer", max_iterations=10)

# DSPy 3.3
rlm = dspy.RLM("context, query -> answer", max_iters=10)

PR: #9920 by @isaacbmiller

RLM Rejects Colliding Names and Unexpected Inputs

RLM now validates its execution namespace up front. Construction fails for duplicate tool names, Python-keyword tool names, signature inputs that collide with built-in sandbox functions or tools, and output fields named trajectory or final_reasoning. Invocation also rejects unexpected input fields rather than ignoring them. Rename colliding fields or tools before constructing the module.

PR: #10020 by @isaacbmiller

RLM Sub-LM and Tool Execution Are Stricter

llm_query and llm_query_batched now require the sub-LM to return either a dspy.LMResponse containing text or a non-empty legacy output list whose first item is text. Arbitrary response objects are no longer converted with str(). Batched queries convert dspy.LMError failures to [ERROR] entries, but programming and response-contract errors now propagate.

RLM also invokes user tools through dspy.Tool, so tool argument validation and coercion, default handling, and tool callbacks now apply.

PRs: #10023, #10025 by @isaacbmiller

Code-Executing Modules Use an Interpreter Factory

ProgramOfThought, CodeAct, and RLM now accept interpreter_factory=, a zero-argument callable that creates a fresh CodeInterpreter for each invocation. This isolates concurrent calls and makes interpreter ownership explicit.

program = dspy.ProgramOfThought(
    "question -> answer",
    interpreter_factory=MyInterpreter,
)

To use an existing interpreter, pass it as the first positional argument when invoking the module. DSPy does not shut down a caller-owned interpreter, and reuse is supported only for sequential calls to the same module instance.

These modules no longer expose a constructor-owned interpreter attribute or preserve its sandbox state across calls. Without a caller-owned interpreter, each invocation creates and shuts down a fresh interpreter. Interpreter process and protocol failures are terminal for that interpreter session rather than automatically restarting it, and submitted-code failures now raise CodeExecutionError, a subclass of CodeInterpreterError.

PRs: #10018, #10022 by @isaacbmiller

`ToolCalls` Uses DSPy's Native Serialized Shape

dspy.ToolCalls.format() and Pydantic serialization now represent each call as {"name": ..., "args": ...} rather than the prior OpenAI-style {"type": "function", "function": {"name": ..., "arguments": ...}} shape. Code that persists ToolCalls, calls .format() directly, or forwards the result to an OpenAI-compatible endpoint must update its conversion logic. Provider adapters still produce the wire shape required by their APIs.

PR: #9823 by @isaacbmiller

Direct `BaseLM` Defaults and Copy Semantics Changed

The direct BaseLM constructor now defaults temperature and max_tokens to None instead of 0.0 and 1000. This primarily affects custom LM subclasses that inherit or delegate to BaseLM.__init__; ordinary dspy.LM already used the provider-default None values.

BaseLM.copy() now shallow-copies subclass-owned attributes while separately copying DSPy-owned mutable runtime containers. Custom LM subclasses that relied on arbitrary mutable attributes being deep-copied should override copy() or copy that state explicitly.

PR: #9821 by @MaximeRivest

Responses Tool Calls Use the Chat-Compatible Legacy Shape

Legacy output from dspy.LM(..., model_type="responses") now represents tool calls in the same shape as the Chat Completions path:

{
    "type": "function",
    "id": call_id,
    "function": {
        "name": tool_name,
        "arguments": arguments,
    },
}

The text key is now always present. Raw Responses item IDs, status, and provider fields remain available through LMToolCallPart.provider_data on the typed path.

PR: #10028 by @isaacbmiller

LM Error Types Are DSPy-Normalized

LM failures are now mapped into DSPy exception classes. This should make LM error handling more consistent, but code that catches provider-specific or LiteLLM-specific errors directly may need to catch dspy.LMError or a narrower DSPy subclass. (#9826 by @MaximeRivest)

ChatAdapter and JSONAdapter no longer retry with an alternate output format after an LMError; provider and transport failures propagate directly. TwoStepAdapter now raises dspy.AdapterParseError rather than ValueError for local extraction or parsing failures, while extraction-LM failures propagate as dspy.LMError.

New and Updated APIs

Added exported LMRequest, LMResponse, typed message/content classes, tool specifications, reasoning and cache configuration, usage records, history entries, and streaming types. (#9786, #9841, #9877 by @MaximeRivest)
Added forward_contract = "typed_lm" and an explicit BaseLM.forward(request) -> LMResponse contract for new custom LM implementations. (#9843, #9877 by @MaximeRivest)
Added Signature.append_instructions() for deriving a signature with additional instructions without mutating the original. (#9923 by @mathurk1)
Added experimental dspy.Flex and trace-aware GEPA metrics through the optional sixth program_trace parameter. (#10047 by @michaelisaac-dev)
Added experimental dspy.ReActV2, structured native tool-call history, and tool-result replay. (#9823, #9824, #9825, #9836 by @isaacbmiller)
Added explicit from_path() and from_url() resource-loading factories for Image and Audio, plus File.from_path(), while keeping construction and validation free of implicit host I/O. (#10111 by @isaacbmiller)
Made BaseLM own and serialize shared runtime state. copy() now makes a shallow object copy, resets history, and separately copies the callbacks list and kwargs dictionary. (#9820, #9821 by @MaximeRivest)
Excluded defaulted arguments from required tool parameters and stabilized open-ended tool argument schemas. (#9971 by @katherineahn, #10012 by @isaacbmiller)
Protected RLM-owned namespaces, normalized sub-LM responses, and routed tool execution through dspy.Tool. (#10020, #10023, #10025 by @isaacbmiller)
Made interpreter process and protocol failures terminal for the affected session and isolated interpreters per invocation. (#10018, #10022 by @isaacbmiller)
Improved interpreter transport for Pydantic objects, scalar values, dataclasses, named tuples, and non-finite floats. (#9753 by @Archelunch, #9991 by @Vinay152003, #10015 and #10049 by @migurski)
Made module load_state() transactional, isolated BootstrapFinetune data by predictor, validated random-search restrictions up front, and preserved callback lineage in parallel workers. (#9741 by @ashishSoni1234, #10005 and #10043 by @isaacbmiller, #10033 by @chuenchen309)

Compatibility Notices

OpenAI 1.66.2 is now the supported minimum. (#9999 by @isaacbmiller)
LiteLLM 1.65.8 is required for the reasoning-capability API. (#10003 by @isaacbmiller)
The LangChain extra now requires LangChain Core 0.3.0 or newer. (#10004 by @isaacbmiller)
The base install no longer depends directly on asyncer, xxhash, or typeguard; DSPy now uses AnyIO and standard-library equivalents. (#9733, #9734, #9735 by @isaacbmiller)
dspy.utils.hasher.Hasher now uses SHA-256 instead of xxhash64. Hash strings, hash-derived fine-tuning filenames, and deterministic bootstrap trace selection may change; LM response-cache keys are unaffected. (#9734 by @isaacbmiller)
Module.set_lm(), get_lm(), and state loading now include module-valued parameter leaves such as Flex, rather than only Predict. Custom classes that combine Module and Parameter should expose compatible LM state and accept allow_unsafe_lm_state= when overriding load_state(). (#10047 by @michaelisaac-dev)

Full PR List

Language Models and Adapters — 23 PRs

#9718 — Handle missing usage from truncated Responses API responses — @isaacbmiller
#9752 — Make LiteLLM imports lazy — @MaximeRivest
#9786 — Add core language-model types — @MaximeRivest
#9791 — Add exact adapter-format message tests — @MaximeRivest
#9792 — Expand exact adapter-format message coverage — @MaximeRivest
#9802 — Introduce a normalized LM boundary for adapters — @MaximeRivest
#9820 — Support BaseLM state serialization — @MaximeRivest
#9821 — Make BaseLM own shared LM runtime state — @MaximeRivest
#9826 — Normalize DSPy LM errors — @MaximeRivest
#9828 — Add the normalized LM API migration plan — @MaximeRivest
#9830 — Fix cached-provider Pydantic serializers — @isaacbmiller
#9834 — Silence missing-input warnings for optional fields — @MaximeRivest
#9837 — Fix GPT-5 LM state round trips — @isaacbmiller
#9840 — Make lazy optional imports thread-safe — @MaximeRivest
#9841 — Export typed LM API symbols — @MaximeRivest
#9843 — Add an explicit BaseLM.forward() contract — @MaximeRivest
#9877 — Make BaseLM.__call__ support typed LMRequest and LMResponse while preserving the legacy default — @MaximeRivest
#9999 — Declare OpenAI 1.66.2 as the supported floor — @isaacbmiller
#10003 — Require the LiteLLM reasoning-capability API — @isaacbmiller
#10014 — Omit absent Responses tool fields — @isaacbmiller
#10026 — Send Responses-native tool and tool_choice shapes — @isaacbmiller
#10028 — Normalize Responses output parsing and unify the legacy tool-call shape — @isaacbmiller
#10111 — Prevent implicit resource loading during validation — @isaacbmiller

Agents, Tools, and Interpreters — 25 PRs

#9411 — Add SandboxSerializable for custom RLM types — @kmad
#9748 — Resolve symlinks for Deno --allow-read paths — @npow
#9753 — Transport Pydantic models as JSON through the interpreter — @Archelunch
#9754 — Await asynchronous tool functions in PythonInterpreter — @Archelunch
#9823 — Preserve tool-call IDs and add tool results — @isaacbmiller
#9824 — Replay native tool-call history through adapters — @isaacbmiller

Note truncated.

Open source →

3.3.0b128 May 2026pre-releaseBreaking

Most existing DSPy programs should keep working without changes. Review the breaking changes if you depend on NumPy from the base dspy install, inspec…

DSPy 3.3.0b1 Release Notes

DSPy 3.3.0b1 is a beta release including a new ReActV2 module, a new BaseLM System, updating to GEPA 0.1.1, and fewer dependencies framework wide.

Most existing DSPy programs should keep working without changes. Review the breaking changes if you depend on NumPy from the base dspy install, inspect GEPA result internals, or catch provider-specific LM exceptions directly.

We would really appreciate feedback on ReActV2 and the new LM system! Please try them out and let us know if you run into any issues.

Highlights

ReActV2 and Native Tool-Calling History - @isaacbmiller

dspy.ReActV2 is a new version of ReAct built around native tool calling. It is currently marked as experimental.

This changes the execution model in a few concrete ways:

parallel_tool_calls support: DSPy preserves each call/result pair by ID. You can do this in native mode or in non-native mode
Multi-turn native tool call support: Prior tool calls and results can be replayed as assistant and tool messages instead of being flattened into prompt text.
Each turn lives in dspy.History as structured messages rather than one ever-growing trajectory string, so providers with prompt caching can reuse stable prefixes more effectively. We have seen up to 50% decreases in cost for some tasks when testing this internally.

PRs: #9823, #9824, #9825, #9835

Typed, Provider-Neutral LM Boundary - @MaximeRivest

DSPy is moving from an untyped LM boundary based on prompt, messages, and provider-shaped kwargs toward a typed, provider-neutral contract:

def forward(self, request: dspy.LMRequest) -> dspy.LMResponse:
    ...

The resulting API is a cleaner LM extension point:

LiteLLM can become an optional compatibility fallback in the planned 3.5+ path, instead of a required part of the core LM contract.
Custom LM authors can implement one typed LMRequest -> LMResponse path instead of guessing which OpenAI/LiteLLM-shaped inputs will arrive.
Custom LMs can translate between DSPy's typed objects and their own provider, local runtime, gateway, or inference stack.
Adapters can start to depend on DSPy's representation of messages, multimodal content, tool calls, reasoning, citations, usage, cache controls, metadata, and stream events.

Most users do not need to change anything in 3.3. Existing lm(...), modules, and programs keep their current behavior by default.

Try out the typed return path with dspy.context(experimental=True), and the public migration plan explains the staged transition for custom LM and adapter authors.

See the full plan here

PRs: #9786, #9802, #9828

Smaller Base Install - @isaacbmiller

We have been whittling away at dependencies!

The base install is lighter: numpy is now optional via dspy[numpy], and direct dependencies on asyncer, xxhash, and typeguard were removed in favor of standard-library paths.

Users who do not need NumPy-backed retrieval, embeddings, or optimizers get a smaller default install with fewer transitive dependencies. Users who need NumPy-backed features can install dspy[numpy].

PRs: #9659, #9733, #9734, #9735

BaseLM Runtime, Save/Load, Errors, and LiteLLM Decoupling - @MaximeRivest

PRs: #9752, #9820, #9821, #9826

Custom Objects for RLM Sandboxes - @kmad

dspy.RLM can now accept custom sandbox-serializable values through SandboxSerializable.

Users can pass richer objects, such as DataFrames, into the sandbox with explicit setup, serialization, assignment, and preview behavior instead of forcing everything through prompt text.

PRs: #9411

GEPA 0.1.1 Support - @BenMcH

DSPy now supports gepa[dspy]==0.1.1, including updated DspyGEPAResult behavior, tests, and docs.

Users can move to the current GEPA DSPy integration in this beta. The breaking changes below call out the result-shape changes for code that inspects detailed GEPA outputs.

PRs: #9673

Breaking Changes

`numpy` Is Now Optional

numpy is no longer installed with base dspy. Features that need NumPy now require the numpy extra:

pip install "dspy[numpy]"

Affected areas include embeddings, KNN/KNNFewShot, SIMBA, and other NumPy-backed optimizer or retrieval paths. (#9659 by @isaacbmiller)

GEPA Result Shapes Changed With `gepa[dspy]==0.1.1`

The upstream GEPA 0.1.1 API changed several result structures, and DspyGEPAResult now mirrors those shapes. Users who inspect optimized_program.detailed_results may need to update code:

DspyGEPAResult.candidates is now a list of compiled DSPy modules, not instruction dictionaries.
DspyGEPAResult.best_candidate now returns a compiled DSPy module.
val_subscores is now list[dict[Any, float]], keyed by validation instance id.
per_val_instance_best_candidates is now dict[Any, set[int]].
best_outputs_valset is now dict[Any, list[tuple[int, Prediction]]] when tracked.
highest_score_achieved_per_val_task now returns a dictionary keyed by validation instance id.

LM Error Types Are Now DSPy-Normalized

LM Runtime Changes

Added core typed LM objects for provider-neutral requests, responses, messages, parts, tool specs, reasoning config, cache config, usage, history entries, stream events, and stream assembly. (#9786 by @MaximeRivest)
Added OpenAI/LiteLLM compatibility conversion helpers so current provider-shaped calls can move through LMRequest and LMResponse internally. (#9802 by @MaximeRivest)
Routed adapter __call__ and acall through the normalized LM boundary while converting back to legacy parser inputs for compatibility. (#9802 by @MaximeRivest)
Current BaseLM calls still receive OpenAI/LiteLLM-shaped kwargs. Internally, adapters now move through adapter messages -> LMRequest -> OpenAI/LiteLLM kwargs -> current BaseLM -> LMResponse -> existing adapter postprocess path. (#9802 by @MaximeRivest)
Added exact adapter-format regression coverage before and during the boundary work, including Chat, JSON, XML, BAML, TwoStep, tools, reasoning, citations, multimodal content, custom types, demos, and history. (#9791, #9792 by @MaximeRivest)
Made BaseLM the owner of shared runtime state and changed BaseLM.copy() to an explicit shallow runtime copy. (#9821 by @MaximeRivest)
Added sanitized BaseLM.dump_state() and BaseLM.load_state() support, including trusted custom LM class loading through allow_unsafe_lm_state=True. (#9820 by @MaximeRivest)
Added structured DSPy LM exceptions and wired them into dspy.LM and adapter fallback behavior. (#9826 by @MaximeRivest)
Made LiteLLM imports lazy so importing DSPy does not eagerly import the LiteLLM bridge. (#9752 by @MaximeRivest)
Added the public typed LM API migration plan for custom LM and adapter authors. (#9828 by @MaximeRivest)

ReActV2 and Tool Calling

Added dspy.ReActV2, a native-tool-aware ReAct predictor with dspy.Tool conversion, an internal submit tool, serialized history input support, unknown-tool and tool-exception handling, and forced final submission when needed. (#9825 by @isaacbmiller)
Enabled ReActV2-style agents to use provider-side parallel tool calls when the adapter is configured with parallel_tool_calls, preserving each model-requested call and each observation by call ID. (#9823, #9824, #9825 by @isaacbmiller)
Moved ReActV2 history from a formatted trajectory string into structured dspy.History, so native-tool providers can see prior turns as assistant/tool messages and prompt-caching providers can reuse stable prompt prefixes more effectively. (#9824, #9825 by @isaacbmiller)
Preserved provider tool-call IDs on ToolCalls.ToolCall and added ToolCallResults for call IDs, tool names, values, and error flags. (#9823 by @isaacbmiller)
Taught adapters to replay prior native assistant tool calls and matching tool results as native LM messages when native function calling is enabled, without changing non-native history rendering. (#9824 by @isaacbmiller)
Rendered tool calls in inspect_history for assistant messages and LM output records, including provider-style function payloads and tool-call outputs without text. (#9835 by @isaacbmiller)

Bug Fixes

Render tool calls in inspect_history and avoid crashing on assistant messages with content=None or output records with tool calls but no text. (#9835 by @isaacbmiller)
Repair cached provider Pydantic serializers when fresh processes read cached OpenAI/LiteLLM response objects with stale MockValSer serializers. (#9830 by @isaacbmiller)
Suppress missing-input warnings for omitted signature inputs whose annotations allow None, while preserving warnings for genuinely missing required inputs. (#9834 by @isaacbmiller)
Handle usage=None from the OpenAI Responses API on truncated responses. (#9718 by @isaacbmiller)
Make module load_state transactional by validating before mutating state. (#9741 by @ashishSoni1234)
Await async tool functions in PythonInterpreter. (#9754 by @Archelunch)
Resolve symlinks correctly for Deno --allow-read paths in PythonInterpreter. (#9748 by @npow)
Remove deprecated Avatar prefix arguments from internal signatures. (#9767 by @nullhack)
Fix a mismatched closing code fence in the README. (#9771 by @abhicris)
Fix the FAQ learn-guide link. (#9798 by @cosmopolitan033)

Docs, Testing, CI, and Dependencies

Added and expanded exact adapter-format message coverage. (#9791, #9792 by @MaximeRivest)
Isolated DSPy cache usage in tests. (#9795 by @isaacbmiller)
Added the normalized LM API migration plan. (#9828 by @MaximeRivest)
Hardened workflows with actionlint/zizmor and SARIF permissions updates. (#9742, #9743, #9745 by @isaacbmiller)
Removed git-auto-commit-action from the release workflow. (#9746 by @isaacbmiller)
Updated actions/setup-python from 3.1.4 to 6.2.0. (#9602 by @dependabot[bot])
Updated runtime/development dependencies including anyio, cachetools, tenacity, weaviate-client, mistune, and zizmor-action. (#9730, #9731, #9732, #9760, #9759, #9787 by @dependabot[bot])

Contributors

@isaacbmiller
@MaximeRivest
@BenMcH
@abhicris
@kmad (first contribution, #9411)
@ashishSoni1234 (first contribution, #9741)
@Archelunch (first contribution, #9754)
@npow (first contribution, #9748)
@nullhack (first contribution, #9767)
@cosmopolitan033 (first contribution, #9798)

Full Changelog: 3.2.1...3.3.0b1

Open source →

3.2.021 Apr 2026Deprecated

Deprecation warning for prefix, format, and parser kwargs in InputField/OutputField by @MaximeRivest

Highlights

BetterTogether Allows Chaining Optimizers — @dilarasoylu

BetterTogether now accepts arbitrary optimizers as keyword arguments and chains them via strategy strings. For example, BetterTogether(metric=m, p=GEPA(...), w=BootstrapFinetune(...)) with strategy="p -> w -> p" will prompt-optimize, fine-tune, then prompt-optimize again -- evaluating each step on a valset and returning the best program. (#9149)

There are many promising strategies that may come from running multiple GEPA steps in sequence, or combining prompt and weight optimization steps in sequence, and we are excited to see what the community comes up with.

Beginning of decoupling DSPy from LiteLLM — @MaximeRivest

@MaximeRivest has an ongoing effort to decouple DSPy from LiteLLM, making it much easier to use custom LMs with DSPy. In this release, adapters no longer import litellm at all -- BaseLM now exposes capability properties (supports_function_calling, supports_reasoning, supports_response_schema, supported_params) and a new dspy.ContextWindowExceededError replaces the litellm error throughout. Custom BaseLM backends can now integrate with DSPy's retry/truncation logic without any litellm dependency. (#9516, #9521, #9522)

Warning on Input field type mismatch — @michaelisaac-dev

Passing a value that doesn't match a signature's declared type now logs a warning (using typeguard). Extra fields not in the signature also warn. Disable with dspy.configure(warn_on_type_mismatch=False). (#9313)

Hardened RLM and PythonInterpreter — @isaacbmiller

Tool calls now use kwargs-only dispatch, the JS tool bridge returns structured errors instead of throwing (preventing Deno crashes), and stdout parsing skips non-JSON lines instead of crashing. Subprocess restarts now correctly replay tool/mount registration. (#9341, #9351)

Notices

Restricted pickle for disk cache

We have added an opt-in dspy.configure_cache(restrict_pickle=True) that swaps pickle.load with a restricted unpickler that only allows litellm/openai types, numpy reconstruction helpers, and user-registered safe_types. Prevents arbitrary code execution from corrupted or malicious cache files. (#9629)

In a future release, we will make this restriction the default behavior.

optuna is now optional

Moved from a required dependency to pip install dspy[optuna]. Saves ~12.7 MB. Only MIPROv2 and BootstrapFewShotWithOptuna use it. (#9397)

All Changes

Features

Make BetterTogether compatible with all optimizers by @dilarasoylu (#9149)
feat: add verify parameter to Image for SSL bypass by @adityasingh2400 (#9279)
feat(signature): add type validation for input fields by @michaelisaac-dev (#9313)
feat: add file output support to inspect_history and fix return type by @bledden (#9321)
feat: make optuna optional by @isaacbmiller (#9397)
feat(retrievers): add EmbeddingsWithScores for similarity score access by @SerjSmor (#9478)
Add XMLAdapter to dspy.ai by @MaximeRivest (#9504)

Bug Fixes

fix(adapters): skip JSON schema for DSPy custom types in prompt by @darinkishore (#9257)
fix: ColBERTv2RetrieverLocal forward method variable scoping bug by @veeceey (#9272)
fix(predict): remove code corruption in ProgramOfThought._parse_code by @adityasingh2400 (#9276)
fix(RLM): show head and tail for RLM outputs by @isaacbmiller (#9282)
fix(rlm): change repl_variable preview to 1000 chars by @isaacbmiller (#9296)
fix(dspy): SemanticF1 and CompleteAndGrounded now return dspy.Prediction by @Copilot (#9302)
refactor(rlm): enhance code fence parsing and REPL entry formatting by @isaacbmiller (#9309)
Fix false rollout_id warning when LM temperature is unset by @okhat (#9316)
fix: pass metric_threshold to BootstrapFewShot for unshuffled case by @kvr06-ai (#9317)
fix: only suggest reducing valset in GEPA when it is large by @bledden (#9320)
fix: make DummyLM delegate to forward() instead of overriding call by @bledden (#9322)
fix: run evaluation on main thread when num_threads=1 by @zamal-db (#9328)
fix(saving): block unsafe LM loading keys by @isaacbmiller (#9334)
fix(settings): add allow_pickle flag to settings loading by @isaacbmiller (#9339)
fix(interpreter): Harden JSONRPC communication and tool bridge by @isaacbmiller (#9341)
fix(interpreter): reset tools/mounts when Deno subprocess restarts by @isaacbmiller (#9351)
fix(adapters): pass use_native_function_calling in JSONAdapter.acall by @isaacbmiller (#9374)
fix(adapters): raise AdapterParseError on empty LM response instead of silent None by @isaacbmiller (#9389)
Deprecation warning for prefix, format, and parser kwargs in InputField/OutputField by @MaximeRivest (#9394)
fix(signature): reject duplicate input and output field names by @MaximeRivest (#9432)
fix(adapter): guard annotation subclass checks for ReAct tool args by @isaacbmiller (#9433)
fix(JSONAdapter): Ensure JSON serialization handles diacritics correctly for Pydantic BaseModel by @matrn (#9493)
Restrict litellm version to <=1.82.6 by @isaacbmiller (#9498)
fix(deps): pin typeguard==4.4.3 to prevent supply chain attacks by @isaacbmiller (#9551)
fix(lm): preserve per-message structure in Responses API conversion by @lawrence3699 (#9580)
fix: cloudpickle serialization of Signature on Python 3.14 by @isaacbmiller (#9616)
fix: correct demo index assignment in MIPROv2 raw_chosen_params by @Ricardo-M-L (#9627)
Fix cache bugs: os.fspath(None) crash, double disk lookups, lazy logging by @isaacbmiller (#9628)
Add restrict_pickle option for safe disk cache deserialization by @isaacbmiller (#9629)
Revert "fix: set LITELLM_LOCAL_MODEL_COST_MAP before litellm import to avoid HTTP fetch" by @isaacbmiller (#9637)
fix(base_lm): guard response.usage access to handle missing usage field by @isaacbmiller (#9638)

Refactors

Refactor: Make DummyLM and callbacks depend on BaseLM instead of LM by @MaximeRivest (#9515)
Refactor: Move model capability checks to BaseLM to remove litellm from adapters by @MaximeRivest (#9516)
Refactor: Introduce DSPy-owned ContextWindowExceededError to decouple error handling by @MaximeRivest (#9521)
refactor: type-hint adapters with BaseLM instead of LM by @MaximeRivest (#9522)

Security

fix(saving): block unsafe LM loading keys by @isaacbmiller (#9334)
Pin CI actions to SHA and replace curl-pipe-bash Deno install by @TomeHirata (#9509)
Create SECURITY.md by @isaacbmiller (#9529)
docs: add ai generated code policy by @isaacbmiller (#9586)

Testing

fix(deno): Add pytest.mark.deno by @isaacbmiller (#9269)

Docs

docs(RLMS): add initial rlm docs by @isaacbmiller (#9264)
fix(docs): Fix tool description on RLM docs by @isaacbmiller (#9270)
fix: correct typo 'occured' to 'occurred' by @thecaptain789 (#9268)
Add R port to community ports documentation by @JamesHWade (#9278)
fix: typo 'itinery_database' to 'itinerary_database' by @TheOnlyWayUp (#9274)
docs(rlm): fix RLM docs consistency and typos by @shirvani-jr (#9280)
Add missing docstrings in dspy/utils/hasher.py by @immerSIR (#9293)
[docs] add Google-style docstrings to Module class by @Tanmay-24 (#9175)
docs: complete llmstxt plugin with full nav sections by @ahmeshaf (#9307)
docs: Add 'Copy page' button to fetch and copy raw Markdown by @zamal-db (#9327)
docs: add Vertex AI (GCP) tab to Language Models guide by @zamal-db (#9329)
docs: clarify max_rounds behavior in BootstrapFewShot by @bledden (#9319)
docs: Update read_output_stream to return final value by @gauravkumar37 (#8977)
Add docstrings to dspy/clients/provider.py by @dev-josias (#9140)
docs: remove n=5 assumption from modules tutorial example by @MaximeRivest (#9380)
docs(evaluate): add docstrings to auto_evaluation.py by @stbiadmin (#9399)
docs: add docstrings to utility functions in utils.py by @Jah-yee (#9371)
Fix/docstring examples section header by @MaximeRivest (#9418)
Enhance docstring for Parallel class by @juntaoyou (#9390)
docs: fix module_end_status_message description in tutorial docs by @paul-tharun (#9144)
Update optimizer import documentation to use modern pattern by @0xRaduan (#8980)
Add API reference pages for dspy.configure and dspy.context by @MaximeRivest (#9445)
Improve dspy.Example docstrings and examples by @MaximeRivest (#9444)
fix(docs): remove broken BetterTogether tutorial links by @isaacbmiller (#9480)
[docs] Remove misleading confidence field from Classification example by @xieyj17 (#9495)
docs: fix duplicate 'the the' typos across docs, source, and tests by @abhicris (#9641)

CI / Infrastructure

chore: bump uv.lock by @isaacbmiller (#9263)
fix(precommit): remove hardcoded python version by @isaacbmiller (#9346)
chore: Add greenlet s390x wheel entries to uv.lock by @isaacbmiller (#9455)
ci: drop unused write permissions from ruff lint job by @isaacbmiller (#9505)
fix(ci): correct setup-node SHA typo in docs-push workflow by @isaacbmiller (#9528)
chore: add dependabot configuration for automated dependency updates by @isaacbmiller (#9592)
chore(dspy): bump gepa from 0.0.26 to 0.0.27 by @isaacbmiller (#9416)
feat(ci): Create PRs with ruff fixes automatically by @isaacbmiller (#9336) -- reverted (#9345)

Dependency updates (Dependabot)

orjson 3.11.2 -> 3.11.8 (#9597)
requests 2.32.4 -> 2.33.1 (#9603)
anthropic 0.54.0 -> 0.89.0 (#9599)
tqdm 4.67.1 -> 4.67.3 (#9623)
pre-commit 4.2.0 -> 4.5.1 (#9622)
denoland/setup-deno 2.0.3 -> 2.0.4 (#9596)
actions/checkout 3.6.0 -> 6.0.2 (#9595)
actions/setup-node 3.9.1 -> 6.3.0 (#9600)
stefanzweifel/git-auto-commit-action 5.2.0 -> 7.1.0 (#9598)
pypa/gh-action-pypi-publish 1.13.0 -> 1.14.0 (#9618)
mkdocs-jupyter 0.25.1 -> 0.26.1 (#9605)
mkdocstrings 0.29.0 -> 1.0.3 (#9609)
mkdocs-material 9.6.9 -> 9.7.6 (#9608)
mkdocs-redirects 1.2.2 -> 1.2.3 (#9607)
mistune 3.0.2 -> 3.2.0 (#9625)

New Contributors

@thecaptain789 made their first contribution in #9268
@TheOnlyWayUp made their first contribution in #9274
@shirvani-jr made their first contribution in #9280
@adityasingh2400 made their first contribution in #9279
@immerSIR made their first contribution in #9293
@Tanmay-24 made their first contribution in #9175
@ahmeshaf made their first contribution in #9307
@kvr06-ai made their first contribution in #9317
@zamal-db made their first contribution in #9327
@bledden made their first contribution in #9319
@gauravkumar37 made their first contribution in #8977
@dev-josias made their first contribution in #9140
@veeceey made their first contribution in #9272
@stbiadmin made their first contribution in #9399
@Jah-yee made their first contribution in #9371
@michaelisaac-dev made their first contribution in #9313
@juntaoyou made their first contribution in #9390
@paul-tharun made their first contribution in #9144
@matrn made their first contribution in #9493
@SerjSmor made their first contribution in

Note truncated.

Open source →

3.1.06 Jan 2026

This is a 3.1.0 official release. We are making the beta release 3.1.0beta1 official.

What's Changed

This is a 3.1.0 official release. We are making the beta release 3.1.0beta1 official.

Optimizers & Evaluation

Add tutorial for dspy-trusted-monitor using GEPA by @ZachParent in #8938
Update gepa[dspy] dependency version to 0.0.18 by @LakshyAAAgrawal in #8969
fix(MIPROv2): zero shot not taking .compile parameters into account before determining if the program was zero shot by @isaacbmiller in #8909
Update gepa[dspy] dependency version to 0.0.22 by @LakshyAAAgrawal in #9042
[docs] Add GEPA gepa_kwargs documentation by @gabrielloiseau in #8998
Update optimizer overview to include the description of SIMBA by @TomeHirata in #9026
Enable callback logging only for full eval on GEPA by @TomeHirata in #9050
Update Arbor Tutorials by @Ziems in #9007
Update RL Tutorial by @Ziems in #9008

Features & Enhancements

Add Disable Fallback Option in ChatAdapter by @Ziems in #8984
Add a method to extract system message based on adapter and signature by @chenmoneygithub in #9006
feat(File): add File type for handling file data by @TomeHirata in #9014
Allow stream listener to work on any type by @chenmoneygithub in #8833
fix(audio): Normalize 'x-wav' audio format to 'wav' by @akshatvishu in #9017
Support Python 3.14 by @TomeHirata in #9041
Introduce dspy.Reasoning to capture native reasoning from reasoning models by @chenmoneygithub in #8986

Security & Serialization

Add guards against loading pkl files by @isaacbmiller in #9048
Add param to load_memory_cache to stop pkl files without explicit loading by @isaacbmiller in #9055

Bug Fixes & Type Handling

Fix TypeError when tracking usage with Anthropic models returning Pydantic objects by @Copilot in #8978
Update old Anthropic model names by @TomeHirata in #8992
fix(XMLAdapter): Implement user message formatting by @BenMcH in #9003
Fix content input conversion for OpenAI Responses API by @Copilot in #8993
Refactor: update type hints for adapter and LM methods by @TomeHirata in #9025
fix(dspy): exclude gpt-5-chat from reasoning model classification by @mindful-time in #9033
fix(dspy): Example.toDict() fails to serialize dspy.History objects by @Copilot in #9047
Some continuous format fix by @chenmoneygithub in #8987

Documentation & Tutorials

Add documentation for provider-side prompt caching with Anthropic and OpenAI by @Copilot in #8970
[docs] Add Google-style docstrings for dspy/evaluate/metrics.py by @eramis73 in #8954
fix: broken PyPI downloads badge from pepy.tech in README and docs home page by @dushmanta05 in #8995
Document ToolCall.execute() availability from dspy 3.0.4b2 by @Copilot in #9004
fix(docs): add python language id to code block by @Ahmad8864 in #9023
docs: add note on Python version for pre-commit by @akshatvishu in #9028
chore(docs): update dspy.settings.configure and dspy.settings.context to dspy.configure and dspy.context by @isaacbmiller in #9060
docs: add documentation for async tool usage and error handling by @TomeHirata in #9054

Minor Fixes, Maintenance & CI

Remove unused notebook python file by @TomeHirata in #8971
Cache Ollama to speed up CI by @TomeHirata in #8972
Clean out unused deps by @isaacbmiller in #8968
docs: add note on Python version for pre-commit by @akshatvishu in #9028
Bump DSPy version by @chenmoneygithub in #9061

New Contributors

@ZachParent made their first contribution in #8938
@eramis73 made their first contribution in #8954
@dushmanta05 made their first contribution in #8995
@akshatvishu made their first contribution in #9017
@mindful-time made their first contribution in #9033
@gabrielloiseau made their first contribution in #8998
@Ahmad8864 made their first contribution in #9023

Full Changelog: 3.0.4...3.1.0b1

Open source →

3.1.0b118 Nov 2025pre-release

This is a pre-release for 3.1.0.

What's Changed

This is a pre-release for 3.1.0.

Optimizers & Evaluation

Add tutorial for dspy-trusted-monitor using GEPA by @ZachParent in #8938
Update gepa[dspy] dependency version to 0.0.18 by @LakshyAAAgrawal in #8969
fix(MIPROv2): zero shot not taking .compile parameters into account before determining if the program was zero shot by @isaacbmiller in #8909
Update gepa[dspy] dependency version to 0.0.22 by @LakshyAAAgrawal in #9042
[docs] Add GEPA gepa_kwargs documentation by @gabrielloiseau in #8998
Update optimizer overview to include the description of SIMBA by @TomeHirata in #9026
Enable callback logging only for full eval on GEPA by @TomeHirata in #9050
Update Arbor Tutorials by @Ziems in #9007
Update RL Tutorial by @Ziems in #9008

Features & Enhancements

Add Disable Fallback Option in ChatAdapter by @Ziems in #8984
Add a method to extract system message based on adapter and signature by @chenmoneygithub in #9006
feat(File): add File type for handling file data by @TomeHirata in #9014
Allow stream listener to work on any type by @chenmoneygithub in #8833
fix(audio): Normalize 'x-wav' audio format to 'wav' by @akshatvishu in #9017
Support Python 3.14 by @TomeHirata in #9041
Introduce dspy.Reasoning to capture native reasoning from reasoning models by @chenmoneygithub in #8986

Security & Serialization

Add guards against loading pkl files by @isaacbmiller in #9048
Add param to load_memory_cache to stop pkl files without explicit loading by @isaacbmiller in #9055

Bug Fixes & Type Handling

Fix TypeError when tracking usage with Anthropic models returning Pydantic objects by @Copilot in #8978
Update old Anthropic model names by @TomeHirata in #8992
fix(XMLAdapter): Implement user message formatting by @BenMcH in #9003
Fix content input conversion for OpenAI Responses API by @Copilot in #8993
Refactor: update type hints for adapter and LM methods by @TomeHirata in #9025
fix(dspy): exclude gpt-5-chat from reasoning model classification by @mindful-time in #9033
fix(dspy): Example.toDict() fails to serialize dspy.History objects by @Copilot in #9047
Some continuous format fix by @chenmoneygithub in #8987

Documentation & Tutorials

Add documentation for provider-side prompt caching with Anthropic and OpenAI by @Copilot in #8970
[docs] Add Google-style docstrings for dspy/evaluate/metrics.py by @eramis73 in #8954
fix: broken PyPI downloads badge from pepy.tech in README and docs home page by @dushmanta05 in #8995
Document ToolCall.execute() availability from dspy 3.0.4b2 by @Copilot in #9004
fix(docs): add python language id to code block by @Ahmad8864 in #9023
docs: add note on Python version for pre-commit by @akshatvishu in #9028
chore(docs): update dspy.settings.configure and dspy.settings.context to dspy.configure and dspy.context by @isaacbmiller in #9060
docs: add documentation for async tool usage and error handling by @TomeHirata in #9054

Minor Fixes, Maintenance & CI

Remove unused notebook python file by @TomeHirata in #8971
Cache Ollama to speed up CI by @TomeHirata in #8972
Clean out unused deps by @isaacbmiller in #8968
docs: add note on Python version for pre-commit by @akshatvishu in #9028
Bump DSPy version by @chenmoneygithub in #9061

New Contributors

@ZachParent made their first contribution in #8938
@eramis73 made their first contribution in #8954
@dushmanta05 made their first contribution in #8995
@akshatvishu made their first contribution in #9017
@mindful-time made their first contribution in #9033
@gabrielloiseau made their first contribution in #8998
@Ahmad8864 made their first contribution in #9023

Full Changelog: 3.0.4...3.1.0b1

Open source →

3.0.410 Nov 2025Deprecated

Deprecate Image from_* helpers in favor of flexible constructor by @isaacbmiller in #8771

3.0.4b2 has been running for a while without seeing issue, so we are making it an official 3.0.4 release.

The release note is the combination of 3.0.4b1 and 3.0.4b2.

What's Changed

Optimizers

Fix GEPA usage tracking with tuple outputs by @smec-cgint in #8739
Add custom instruction_proposer support to GEPA with multimodal (dspy.Image) handling by @andressrg in #8737
Enhance logging for valset usage in GEPA by @LakshyAAAgrawal in #8770
[Feature] GEPA: Add custom component selection logic support by @andressrg in #8765
Add MLFLow <> GEPA support by @TomeHirata in #8763
Update optimization overview with data split guidance by @LakshyAAAgrawal in #8792
docs: Add comprehensive instruction_proposer documentation and examples for GEPA by @andressrg in #8775
Introduce gepa_kwargs for passing custom kwargs to gepa.optimize by @LakshyAAAgrawal in #8850
Propagate callback metadata during GEPA minibatch eval by @TomeHirata in #8835
Fix typo in GEPA warning by @TomeHirata in #8840
Update gepa[dspy] dependency version to 0.0.17; Potential fix for load from state not working in GEPA by @LakshyAAAgrawal in #8859
SIMBA Improvements by @klopsahlong in #8766

Features & Enhancements

Add Anthropic Citation API support by @TomeHirata in #8721
Add api reference for citations and document by @TomeHirata in #8801
Allow custom type to be streamed and use native response by @TomeHirata in #8778
Fix example code for Citations by @TomeHirata in #8868
Add ToolCall.execute for smoother tool execution (#8825, @TomeHirata)
Add DSPy User-Agent header (#8887, @TomeHirata)
Update headers when specified (#8893, @TomeHirata)
Arbor GRPO Sync Update (#8939, @Ziems)
Deprecate Image from_* helpers in favor of flexible constructor by @isaacbmiller in #8771
Cache Image.format for better throughput by @TomeHirata in #8842
test(dspy.Image): Adds a test with ReAct that has an Image tool by @isaacbmiller in #8855

Bug Fixes & Type Handling

Fix #8703 - fixing module and feedback mismatch by @Lucas-Fernandes-Martins in #8777
Fix value parsing and add tests by @chenmoneygithub in #8774
Parse doubly-encoded base type in json.parse by @TomeHirata in #8814
Fix unexpected parsing of Optional[str] fields when string has brackets or braces by @sontanon in #8805
Use mcp.ClientSession for type hint by @TomeHirata in #8826
Fix type hint for callpreprocess by @TomeHirata in #8827
fix: Allow DummyLM answers dict values to be of any type to work with a wider range of signatures by @BenMcH in #8803
Fix the crash when usage tracker is enabled with non-prediction output by @TomeHirata in #8831
Fallback to memory cache when disk is not available by @TomeHirata in #8718
bug(lm): Avoid unnecessary cache key computation by @isaacbmiller in #8862
Display metric=0 in eval table by @TomeHirata in #8817
Add save/load to Embeddings by @TomeHirata in #8818
Fix chunk loss in long streaming with native response field (#8881, @TomeHirata)
Make the buffer condition more precise (#8907, @TomeHirata)
fix: add fallback on missing end marker during streaming (#8890, @enitrat)
fix(JSONAdapter): escape logic when JSON mode but no structured outputs (#8871, @isaacbmiller)
fix: XML adapter markers (#8876, @enitrat)
Fix test_xml_adapter_full_prompt (#8904, @TomeHirata)
Fix responses API (#8880, @chenmoneygithub)
Fix response_format handling for responses API (#8911, @TomeHirata)
Fix error handling in dspy parallel (#8860, @TomeHirata)
fix(LM): default temperature and max_tokens to None (#8908, @isaacbmiller)
fix(MIPROv2): select between task_model and prompt_model (#8877, @isaacbmiller)
Exclude API keys from saved programs (#8941, @Copilot)

Documentation & Tutorials

Minor document changes by @Navanit-git in #8722
Add doc page to learn tool usage in DSPy by @TomeHirata in #8709
Style fix for tool page by @TomeHirata in #8781
Add tracing banner in new tutorials by @B-Step62 in #8772
docs: fix link to the sglang installation/getting started page by @tomsanbear in #8776
Guide on using native tool calling by @chenmoneygithub in #8788
fix: removed duplicate cell from GEPA information extraction tutorial by @vacmar01 in #8806
Remove EmailInsight class from email extraction tutorial by @TomeHirata in #8790
Update documentation to include responses api by @chenmoneygithub in #8780
[Feature] Add automatic llms.txt generation via mkdocs-llmstxt plugin by @aberoham in #8562
Guide on using native tool calling by @chenmoneygithub in #8788
Update HotPotQA in light of #8591 by @okhat in #8751
Add Learn MCP page (#8903, @TomeHirata)
Fix MIPRO paper link in RAG tutorial (#8937, @TomeHirata)
[Docstring] Add docstring for Adapter (#8915, @chenmoneygithub)
[Docs] Google-style docstrings for dspy/primitives/example Example class (#8949, @Davshiv20)
[Docs] Google-style docstrings for Signature.prepend/append/insert/delete (#8945, @gnetsanet)
Better tutorial sidebar—do not auto-expand all tutorials (#8912, @chenmoneygithub)

Minor Fixes & Maintenance

Use developer role in response API by @TomeHirata in #8727
8688 csv output by @crawftv in #8725
Add header link by @TomeHirata in #8773
Add experimental annotation by @TomeHirata in #8712
Update LICENSE error by @TomeHirata in #8783
Fixed Spelling error in DatasetDescriptor Prompt by @PoeAudits in #8812
Update API reference by @TomeHirata in #8844
Expose EvaluationResult as dspy.evaluate.EvaluationResult by @TomeHirata in #8843
Include built-in types in DSPy api references by @chenmoneygithub in #8810
Change DummyLM to take an adapter at init by @isaacbmiller in #8802
Infinitus AI agents by @suman-subash-infinitusai in #8708
[WIP] Arbor Interface Update by @Ziems in #8837
Refactor URL construction in ArborReinforceJob to use urljoin (#8951, @Ziems)
Update type hint of ClientSession (#8894, @TomeHirata)
Long line in function signature (style) (#8914, @chenmoneygithub)
Fix lint of LM (#8884, @chenmoneygithub)
Deflake the real LM test (#8924, @chenmoneygithub)

New Contributors

@crawftv made their first contribution in https://github.com/stanfordnlp/dspy/pull/8725
@Navanit-git made their first contribution in https://github.com/stanfordnlp/dspy/pull/8722
@smec-cgint made their first contribution in https://github.com/stanfordnlp/dspy/pull/8739
@suman-subash-infinitusai made their first contribution in https://github.com/stanfordnlp/dspy/pull/8708
@andressrg made their first contribution in https://github.com/stanfordnlp/dspy/pull/8737
@tomsanbear made their first contribution in https://github.com/stanfordnlp/dspy/pull/8776
@Lucas-Fernandes-Martins made their first contribution in https://github.com/stanfordnlp/dspy/pull/8777
@aberoham made their first contribution in https://github.com/stanfordnlp/dspy/pull/8562
@PoeAudits made their first contribution in https://github.com/stanfordnlp/dspy/pull/8812
@sontanon made their first contribution in https://github.com/stanfordnlp/dspy/pull/8805
@enitrat made their first contribution in https://github.com/stanfordnlp/dspy/pull/8890
@Davshiv20 made their first contribution in https://github.com/stanfordnlp/dspy/pull/8949
@gnetsanet made their first contribution in https://github.com/stanfordnlp/dspy/pull/8945

Full Changelog: https://github.com/stanfordnlp/dspy/compare/3.0.3...3.0.4

Open source →

3.0.4b221 Oct 2025pre-release

Add ToolCall.execute for smoother tool execution (#8825, @TomeHirata)

What's Changed

Features & Enhancements

Tooling / APIs
- Add ToolCall.execute for smoother tool execution (#8825, @TomeHirata)
Networking / Headers
- Add DSPy User-Agent header (#8887, @TomeHirata)
- Update headers when specified (#8893, @TomeHirata)
Arbor / RL
- Arbor GRPO Sync Update (#8939, @Ziems)

Bug Fixes & Reliability

Streaming / Buffers
- Fix chunk loss in long streaming with native response field (#8881, @TomeHirata)
- Make the buffer condition more precise (#8907, @TomeHirata)
- fix: add fallback on missing end marker during streaming (#8890, @enitrat)
Adapters
- fix(JSONAdapter): escape logic when JSON mode but no structured outputs (#8871, @isaacbmiller)
- fix: XML adapter markers (#8876, @enitrat)
- Fix test_xml_adapter_full_prompt (#8904, @TomeHirata)
Responses / APIs
- Fix responses API (#8880, @chenmoneygithub)
- Fix response_format handling for responses API (#8911, @TomeHirata)
Core / LM
- Fix error handling in dspy parallel (#8860, @TomeHirata)
- fix(LM): default temperature and max_tokens to None (#8908, @isaacbmiller)
MIPRO
- fix(MIPROv2): select between task_model and prompt_model (#8877, @isaacbmiller)

Security & Privacy

Exclude API keys from saved programs (#8941, @Copilot)

Refactors & Maintenance

Refactor URL construction in ArborReinforceJob to use urljoin (#8951, @Ziems)
Update type hint of ClientSession (#8894, @TomeHirata)
Long line in function signature (style) (#8914, @chenmoneygithub)
Fix lint of LM (#8884, @chenmoneygithub)

Documentation

Add Learn MCP page (#8903, @TomeHirata)
Fix MIPRO paper link in RAG tutorial (#8937, @TomeHirata)
[Docstring] Add docstring for Adapter (#8915, @chenmoneygithub)
[Docs] Google-style docstrings for dspy/primitives/example Example class (#8949, @Davshiv20)
[Docs] Google-style docstrings for Signature.prepend/append/insert/delete (#8945, @gnetsanet)
Better tutorial sidebar—do not auto-expand all tutorials (#8912, @chenmoneygithub)

Tests & Stability

Deflake the real LM test (#8924, @chenmoneygithub)

New Contributors

@enitrat made their first contribution in https://github.com/stanfordnlp/dspy/pull/8890
@Copilot made their first contribution in https://github.com/stanfordnlp/dspy/pull/8941
@Davshiv20 made their first contribution in https://github.com/stanfordnlp/dspy/pull/8949
@gnetsanet made their first contribution in https://github.com/stanfordnlp/dspy/pull/8945

Full Changelog: https://github.com/stanfordnlp/dspy/compare/3.0.4b1...3.0.4b2

Open source →

3.0.4b129 Sept 2025pre-releaseDeprecated

Deprecate Image from_* helpers in favor of flexible constructor by @isaacbmiller in #8771

What's Changed

GEPA + Other Optimizers

Fix GEPA usage tracking with tuple outputs by @smec-cgint in #8739
Add custom instruction_proposer support to GEPA with multimodal (dspy.Image) handling by @andressrg in #8737
Enhance logging for valset usage in GEPA by @LakshyAAAgrawal in #8770
[Feature] GEPA: Add custom component selection logic support by @andressrg in #8765
Add MLFLow <> GEPA support by @TomeHirata in #8763
Update optimization overview with data split guidance by @LakshyAAAgrawal in #8792
docs: Add comprehensive instruction_proposer documentation and examples for GEPA by @andressrg in #8775
Introduce gepa_kwargs for passing custom kwargs to gepa.optimize by @LakshyAAAgrawal in #8850
Propagate callback metadata during GEPA minibatch eval by @TomeHirata in #8835
Fix typo in GEPA warning by @TomeHirata in #8840
Update gepa[dspy] dependency version to 0.0.17; Potential fix for load from state not working in GEPA by @LakshyAAAgrawal in #8859
SIMBA Improvements by @klopsahlong in #8766

Custom Type

Add Anthropic Citation API support by @TomeHirata in #8721
Add api reference for citations and document by @TomeHirata in #8801
Allow custom type to be streamed and use native response by @TomeHirata in #8778
Fix example code for Citations by @TomeHirata in #8868

Image & Multimodal Support

Deprecate Image from_* helpers in favor of flexible constructor by @isaacbmiller in #8771
Cache Image.format for better throughput by @TomeHirata in #8842
test(dspy.Image): Adds a test with ReAct that has an Image tool by @isaacbmiller in #8855

Bug Fixes & Type Handling

Fix #8703 - fixing module and feedback mismatch by @Lucas-Fernandes-Martins in #8777
Fix value parsing and add tests by @chenmoneygithub in #8774
Parse doubly-encoded base type in json.parse by @TomeHirata in #8814
Fix unexpected parsing of Optional[str] fields when string has brackets or braces by @sontanon in #8805
Use mcp.ClientSession for type hint by @TomeHirata in #8826
Fix type hint for callpreprocess by @TomeHirata in #8827
fix: Allow DummyLM answers dict values to be of any type to work with a wider range of signatures by @BenMcH in #8803
Fix the crash when usage tracker is enabled with non-prediction output by @TomeHirata in #8831
Fallback to memory cache when disk is not available by @TomeHirata in #8718
bug(lm): Avoid unnecessary cache key computation by @isaacbmiller in #8862
Display metric=0 in eval table by @TomeHirata in #8817
Add save/load to Embeddings by @TomeHirata in #8818

Documentation & Tutorials

Minor document changes by @Navanit-git in #8722
Add doc page to learn tool usage in DSPy by @TomeHirata in #8709
Style fix for tool page by @TomeHirata in #8781
Add tracing banner in new tutorials by @B-Step62 in #8772
docs: fix link to the sglang installation/getting started page by @tomsanbear in #8776
Guide on using native tool calling by @chenmoneygithub in #8788
fix: removed duplicate cell from GEPA information extraction tutorial by @vacmar01 in #8806
Remove EmailInsight class from email extraction tutorial by @TomeHirata in #8790
Update documentation to include responses api by @chenmoneygithub in #8780
[Feature] Add automatic llms.txt generation via mkdocs-llmstxt plugin by @aberoham in #8562
Guide on using native tool calling by @chenmoneygithub in #8788
Update HotPotQA in light of #8591 by @okhat in #8751

Minor Fixes & Maintenance

Use developer role in response API by @TomeHirata in #8727
8688 csv output by @crawftv in #8725
Add header link by @TomeHirata in #8773
Add experimental annotation by @TomeHirata in #8712
Update LICENSE error by @TomeHirata in #8783
Fixed Spelling error in DatasetDescriptor Prompt by @PoeAudits in #8812
Update API reference by @TomeHirata in #8844
Expose EvaluationResult as dspy.evaluate.EvaluationResult by @TomeHirata in #8843
Include built-in types in DSPy api references by @chenmoneygithub in #8810
Change DummyLM to take an adapter at init by @isaacbmiller in #8802
Infinitus AI agents by @suman-subash-infinitusai in #8708
[WIP] Arbor Interface Update by @Ziems in #8837

New Contributors

@crawftv made their first contribution in https://github.com/stanfordnlp/dspy/pull/8725
@Navanit-git made their first contribution in https://github.com/stanfordnlp/dspy/pull/8722
@smec-cgint made their first contribution in https://github.com/stanfordnlp/dspy/pull/8739
@suman-subash-infinitusai made their first contribution in https://github.com/stanfordnlp/dspy/pull/8708
@andressrg made their first contribution in https://github.com/stanfordnlp/dspy/pull/8737
@tomsanbear made their first contribution in https://github.com/stanfordnlp/dspy/pull/8776
@Lucas-Fernandes-Martins made their first contribution in https://github.com/stanfordnlp/dspy/pull/8777
@aberoham made their first contribution in https://github.com/stanfordnlp/dspy/pull/8562
@PoeAudits made their first contribution in https://github.com/stanfordnlp/dspy/pull/8812
@sontanon made their first contribution in https://github.com/stanfordnlp/dspy/pull/8805

Full Changelog: https://github.com/stanfordnlp/dspy/compare/3.0.3...3.0.4b1

Open source →

3.0.012 Aug 2025Deprecated

Various deprecations promised in 2.5 were applied during the 2.6.0 release candidates (e.g., old functional/, dsp/ clients, legacy caches/examples/tes…

DSPy 3.0.0

The work in the run up to DSPy 3.0 has focused on new powerful optimizers (RL: dspy.GRPO via our new Arbor library; and reflective prompt evolution: dspy.GEPA and dspy.SIMBA), extensibility (dspy.Adapter & dspy.Type), reliability/observability for production (tight integration with MLflow 3.0), and more. Much of this work incubated during late 2.6 and matured in 3.0.

✨ Highlights across 2.6 → 3.0

Adapters & Types (extensibility without prompt plumbing)

Adapters: built-in dspy.ChatAdapter, dspy.JSONAdapter, dspy.XMLAdapter, dspy.BAMLAdapter, token/status streaming, async paths, and intelligent fallback to native LLM structured outputs.
Types: multi-modal I/O via dspy.Image and dspy.Audio; composite types (e.g., list[dspy.Image], Pydantic models); higher-level I/O like dspy.History and dspy.ToolCalls. Custom types now “just work” with adapters (dspy.Type).
Tooling integrations: MCP servers and LangChain tools supported out-of-the-box.

Modules, Runtime & DX

Better scalability: Module.batch with thread-safe DSPy settings; native DSPy async; high-concurrency, configurable caches.
Smoother DX: intermediate status streaming, output streaming from any layer, usage tracking, per-module history, rich callbacks.
Deployment/portability: stable save/load (including the program), and you can export the prompt management layer via Adapters.
New/updated modules: dspy.CodeAct, dspy.Refine, improved ReAct, a more reliable PythonInterpreter.

Observability & MLOps

Native observability with MLflow 3.0: tracing, optimizer tracking, and improved deployment flows (plus docs/tutorials).

Optimizers

MIPROv2: substantially more reliable with automatic hyperparameter selection and many fixes.
GRPO (RL on DSPy programs): our new Arbor library for RL training of compound AI systems.
SIMBA: powerful prompt optimizer that learns from custom feedback (great for agentic/long-horizon tasks).
GEPA (Genetic-Pareto): a new optimizer that builds a Pareto tree of prompts, uses NL reflection to extract/validate lessons, and can produce shorter prompts while improving downstream performance. Early results show wins over MIPROv2 on several tasks and promising inference-time search behavior (see paper announcement for details).

Some of the above first landed in late 2.6 (e.g., early streaming, initial adapters/types improvements), and were consolidated/matured in 3.0.

💥 Breaking changes / notable removals

Remove community retrievers (#8073). If you relied on unmaintained retriever integrations, migrate to custom code (or use Tool/MCP integrations).
Drop Python 3.9 support. 3.10–3.13 are supported.
Alias removed: dspy.Program → remove/replace (was cleaned up in 3.0 work).
Various deprecations promised in 2.5 were applied during the 2.6.0 release candidates (e.g., old functional/, dsp/ clients, legacy caches/examples/tests).

🆚 Changes since `3.0.0b4`

Optimizers

Add GEPA (Genetic-Pareto) optimizer (@LakshyAAAgrawal, #8624, #8628, #8633).

Maintenance

Migrate GitHub Actions from set-output to $GITHUB_OUTPUT (@kurtmckee, #8557).

New contributor

@LakshyAAAgrawal (first contribution in #8624).

Full Changelog: 3.0.0b4...3.0.0

📚 3.0.0 beta highlights (rollup)

b4: MIPRO reliability fixes; updated Arbor GRPO integration; streaming end-marker; faster image JSON parsing; BAMLAdapter; mark gpt-5 as reasoning model; vendor a lighter internal hasher. New contributors: @weklund, @vakinapalli, @tvdaptible, @jmhb0, @olesyash, @kurtmckee, @prrao87, @danielsparing, @apieum.
b3: dspy.Code; PEP 604 unions in signatures; token streaming for XMLAdapter; dspy.syncify for running optimizers on async DSPy programs; Windows support for MIPROv2 confirm; real-LLM unit tests. New contributors: @LukasMurdock, @ken-dwyer, @grisaitis, @vacmar01, @fswair, @nillwyc, @asad-aali, @niklovescoding, @MaximeRivest, @brenorb.
b2: Stream listener reuse; async paths for Chat/JSON adapters; error-message/QoL updates; drop Python 3.9; docs/tutorials; rename BaseType → Type; remove dspy.Program alias; many cleanups. New contributors: @codingDuan, @Hangzhi, @poudro.
b1: 3.0 “heads-up” + remove unmaintained retrievers (#8073); XML adapter; standardize/style improvements; async settings merge; MLflow tracing guide. New contributors: @brishin, @dmavrommatis.

👏 Contributors since 2.6

Thank you to everyone who contributed code, docs, reviews, issues, and testing!

🎉 = first-time contributor since 2.6.15

@AkeemMcLennon, @aliirz, @amas0, @apieum 🎉, @arnavsinghvi11, @asad-aali 🎉, @asparagus, @assadyousuf 🎉, @BenMcH 🎉, @bjsi, @brenorb 🎉, @brishin 🎉, @BTripp1986 🎉, @carsonkahn-external 🎉, @cezarc1, @chakravarthik27, @charviupreti 🎉, @chenmoneygithub, @codingDuan 🎉, @CyrusNuevoDia, @danielsparing 🎉, @dbczumar, @dilarasoylu, @dimroc, @Dyadd, @emmanuel-ferdman 🎉, @erandeutsch, @estsauver, @fswair 🎉, @GabeDottl, @glesperance, @grisaitis 🎉, @hmoazam, @Harryllh, @Hangzhi, @hung-phan, @isaacbmiller, @itay1542, @Jdogtherock, @JHMuir, @jjjjw, @jinnovation, @jmho, @jmhb0 🎉, @kanjurer, @kalanyuz, @ken-dwyer 🎉, keyuchen21, @klopsahlong, @koptagel 🎉, @kurtmckee 🎉, @LukasMurdock 🎉, @laitifranz, @LakshyAAAgrawal 🎉, @lxdlam, @MaximeRivest 🎉, @MaxwellSalmon, @Miyamura80 🎉, @myz96, @neilbhutada, @niklovescoding 🎉, @nillwyc 🎉, @okhat, @olesyash 🎉, @poudro 🎉, @prrao87 🎉, @patcher9, @rcanand, @rifolio 🎉, @Samoed, @SanjanShiv 🎉, @srowen 🎉, @Shangyint, @stevapple, @tvdaptible 🎉, @TomeHirata, @tikoehle 🎉, @Timtech4u, @thomasahle, @ulgens, @vakinapalli 🎉, @vacmar01 🎉, @veronicalyu320, @vincentkoc, @weklund 🎉, @willsmithDB, @xinyij-goo 🎉, @yuruofeifei, @Ziems, @zbambergerNLP, @gkorland, @yanmxa, @mikeedjones, @b-d055, @mikeweltevredem, @ItzAmirreza, @GangGreenTemperTatum, @shermansiu, @dmavrommatis, @iPersona, @Krishn1412, @Y-1huadb, @B-Step62, @tkellogg

First-time contributors called out since 2.6.15 (rollup): @rifolio, @charviupreti, @BenMcH, @GangGreenTemperTatum, @koptagel, @Miyamura80, @tikoehle, @srowen, @assadyousuf, @xinyij-goo, @SanjanShiv, @emmanuel-ferdman, @Y-1huadb, @Krishn1412, @BTripp1986, @vincentkoc, @estsauver, @jmho, @JHMuir, @neilbhutada, @carsonkahn-external, @dimroc, @erandeutsch, @willsmithDB, @iPersona, @brishin, @dmavrommatis, @codingDuan, @Hangzhi, @poudro, @LukasMurdock, @ken-dwyer, @grisaitis, @vacmar01, @fswair, @nillwyc, @asad-aali, @niklovescoding, @MaximeRivest, @brenorb, @weklund, @vakinapalli, @tvdaptible, @jmhb0, @olesyash, @kurtmckee, @prrao87, @danielsparing, @apieum, @LakshyAAAgrawal.

🔗 Compare

Full changes: 2.6.27...3.0.0b1, 3.0.0b1...3.0.0b2, 3.0.0b2...3.0.0b3, 3.0.0b3...3.0.0b4, 3.0.0b4...3.0.0.

Open source →

3.0.0b411 Aug 2025pre-release

Fixes for MIPRO: Don't fail silently on bootstrapping! by @okhat in https://github.com/stanfordnlp/dspy/pull/8548

What's Changed

Optimizers

Fixes for MIPRO: Don't fail silently on bootstrapping! by @okhat in https://github.com/stanfordnlp/dspy/pull/8548
skip unhashable module histories for mipro program proposer by @arnavsinghvi11 in https://github.com/stanfordnlp/dspy/pull/8572
Update Arbor GRPO Integration by @Ziems in https://github.com/stanfordnlp/dspy/pull/8609
Remove user confirmation from MiproV2 by @TomeHirata in https://github.com/stanfordnlp/dspy/pull/8552

Adapters & Tools

fix(dspy): Fix MCP tool conversion when schema has no input params by @tvdaptible in https://github.com/stanfordnlp/dspy/pull/8566
Explicitly mark the end of streaming by @chenmoneygithub in https://github.com/stanfordnlp/dspy/pull/8587
faster json parsing for images in chatadapter by @jmhb0 in https://github.com/stanfordnlp/dspy/pull/8596
Use json mode for serialization by @TomeHirata in https://github.com/stanfordnlp/dspy/pull/8605
Custom BAMLAdapter to improve structured outputs by @prrao87 in https://github.com/stanfordnlp/dspy/pull/8614

LMs & Modules

Mark gpt-5 as reasoning model by @olesyash in https://github.com/stanfordnlp/dspy/pull/8620
Fix infinite growing trace and add tests by @chenmoneygithub in https://github.com/stanfordnlp/dspy/pull/8607
Litellm logging management by @chenmoneygithub in https://github.com/stanfordnlp/dspy/pull/8619
nit: fix "poorly-design" by @danielsparing in https://github.com/stanfordnlp/dspy/pull/8622
remove history and callbacks from module saving by @arnavsinghvi11 in https://github.com/stanfordnlp/dspy/pull/8599
update deduplicate by @apieum in https://github.com/stanfordnlp/dspy/pull/8623

Maintenance

Increment python version for pre-commit by @TomeHirata in https://github.com/stanfordnlp/dspy/pull/8602
Run the typos tool against the codebase by @kurtmckee in https://github.com/stanfordnlp/dspy/pull/8560
Fix incorrect build-system requirements by @kurtmckee in https://github.com/stanfordnlp/dspy/pull/8558
Vendor Hasher class from datasets library in order to remove larger dependency by @BenMcH in https://github.com/stanfordnlp/dspy/pull/8621

New Contributors

@weklund made their first contribution in https://github.com/stanfordnlp/dspy/pull/8554
@vakinapalli made their first contribution in https://github.com/stanfordnlp/dspy/pull/8569
@tvdaptible made their first contribution in https://github.com/stanfordnlp/dspy/pull/8566
@jmhb0 made their first contribution in https://github.com/stanfordnlp/dspy/pull/8596
@olesyash made their first contribution in https://github.com/stanfordnlp/dspy/pull/8620
@kurtmckee made their first contribution in https://github.com/stanfordnlp/dspy/pull/8560
@prrao87 made their first contribution in https://github.com/stanfordnlp/dspy/pull/8614
@danielsparing made their first contribution in https://github.com/stanfordnlp/dspy/pull/8622
@apieum made their first contribution in https://github.com/stanfordnlp/dspy/pull/8623

Full Changelog: https://github.com/stanfordnlp/dspy/compare/3.0.0b3...3.0.0b4

Open source →

3.0.0b319 Jul 2025pre-release

Key bugfix: The removal of datasets from the default dependencies in 3.0.0b1 meant that if the user didn't have datasets installed, the bootstrapping

What's Changed

Key bugfix: The removal of datasets from the default dependencies in 3.0.0b1 meant that if the user didn't have datasets installed, the bootstrapping of MIPROv2 would fail silently, leading to worse optimization. Added datasets back in commit 8aa065945.

Signatures, Adapters, & Types

add dspy.Code by @chenmoneygithub in https://github.com/stanfordnlp/dspy/pull/8511
Provide language to dspy.Code by @chenmoneygithub in https://github.com/stanfordnlp/dspy/pull/8519
Use collections for type hints by @TomeHirata in https://github.com/stanfordnlp/dspy/pull/8513
Add testing for PEP604 union types by @erandeutsch in https://github.com/stanfordnlp/dspy/pull/8475
Fix type annotation for ensure_signature by @grisaitis in https://github.com/stanfordnlp/dspy/pull/8496
Use model_dump instead of dict by @TomeHirata in https://github.com/stanfordnlp/dspy/pull/8493
Fix native function calling in adapters by @chenmoneygithub in https://github.com/stanfordnlp/dspy/pull/8479
Rename dspy.BaseType to dspy.Type by @chenmoneygithub in https://github.com/stanfordnlp/dspy/pull/8510
Resolve "$def" for nested tool arg type by @chenmoneygithub in https://github.com/stanfordnlp/dspy/pull/8534
Add token streaming support for XMLAdapter by @chenmoneygithub in https://github.com/stanfordnlp/dspy/pull/8478

Modules

Update python_interpreter.py by @nillwyc in https://github.com/stanfordnlp/dspy/pull/8501
unwrap pyodide object correctly by @arnavsinghvi11 in https://github.com/stanfordnlp/dspy/pull/8466
Provide a dspy.syncify so that users can run optimizer on async dspy programs by @chenmoneygithub in https://github.com/stanfordnlp/dspy/pull/8509
fix UnicodeDecodeError: 'gbk' codec can't decode by @nillwyc in https://github.com/stanfordnlp/dspy/pull/8522

Other

Support MIPROv2 user confirmation in windows by @TomeHirata in https://github.com/stanfordnlp/dspy/pull/8485
Run unit tests with real LLM calls by @TomeHirata in https://github.com/stanfordnlp/dspy/pull/8486

New Contributors

@LukasMurdock made their first contribution in https://github.com/stanfordnlp/dspy/pull/8477
@ken-dwyer made their first contribution in https://github.com/stanfordnlp/dspy/pull/8474
@grisaitis made their first contribution in https://github.com/stanfordnlp/dspy/pull/8496
@vacmar01 made their first contribution in https://github.com/stanfordnlp/dspy/pull/8499
@fswair made their first contribution in https://github.com/stanfordnlp/dspy/pull/8498
@nillwyc made their first contribution in https://github.com/stanfordnlp/dspy/pull/8501
@asad-aali made their first contribution in https://github.com/stanfordnlp/dspy/pull/8512
@niklovescoding made their first contribution in https://github.com/stanfordnlp/dspy/pull/8515
@MaximeRivest made their first contribution in https://github.com/stanfordnlp/dspy/pull/8527
@brenorb made their first contribution in https://github.com/stanfordnlp/dspy/pull/8542

Full Changelog: https://github.com/stanfordnlp/dspy/compare/3.0.0b2...3.0.0b3

Open source →

3.0.0b21 Jul 2025pre-release

Remove dspy.Program alias by @TomeHirata in https://github.com/stanfordnlp/dspy/pull/8392

What's Changed

Modules & Adapters

Remove dspy.Program alias by @TomeHirata in https://github.com/stanfordnlp/dspy/pull/8392
Clean up ChainOfThoughtWithHint in DSPy 3.0 by @Hangzhi in https://github.com/stanfordnlp/dspy/pull/8395
Change the output interface of evaluate by @TomeHirata in https://github.com/stanfordnlp/dspy/pull/8003
Add format to ToolCalls by @TomeHirata in https://github.com/stanfordnlp/dspy/pull/8455
Allow reusing the stream listener by @chenmoneygithub in https://github.com/stanfordnlp/dspy/pull/8461

Bug Fixes

Fix the issue that StreamListener strip out space after the start identifier by @chenmoneygithub in https://github.com/stanfordnlp/dspy/pull/8360
Fix the streaming test by @chenmoneygithub in https://github.com/stanfordnlp/dspy/pull/8367
fix bedrock streaming token tracking by @BTripp1986 in https://github.com/stanfordnlp/dspy/pull/8431
Allow exception to pass through in JSONAdapter by @chenmoneygithub in https://github.com/stanfordnlp/dspy/pull/8445
Support async path for ChatAdapter and JSONAdapter by @chenmoneygithub in https://github.com/stanfordnlp/dspy/pull/8419
Fix PEP 604 union types when using Class Signatures for ChainOfThought by @erandeutsch in https://github.com/stanfordnlp/dspy/pull/8465

QoL

Improve error message on invalid lm setup by @chenmoneygithub in https://github.com/stanfordnlp/dspy/pull/8378
Show warning if forward is directly called by @TomeHirata in https://github.com/stanfordnlp/dspy/pull/8380

Style

Small style fix on forward call warning by @chenmoneygithub in https://github.com/stanfordnlp/dspy/pull/8381
Add quote rule to the lint rules by @TomeHirata in https://github.com/stanfordnlp/dspy/pull/8383
Refactor root init file by @TomeHirata in https://github.com/stanfordnlp/dspy/pull/8385
Add missing rule comment by @chenmoneygithub in https://github.com/stanfordnlp/dspy/pull/8398
Consistently use double quotes in DSPy docsite landing page by @chenmoneygithub in https://github.com/stanfordnlp/dspy/pull/8447

Maintenance

Remove pandas and datasets from core dependencies by @TomeHirata in https://github.com/stanfordnlp/dspy/pull/8274
Update dspy version in uv lock by @TomeHirata in https://github.com/stanfordnlp/dspy/pull/8384
Remove Hyperparameter class by @TomeHirata in https://github.com/stanfordnlp/dspy/pull/8386
Remove unused multi-hop state files by @TomeHirata in https://github.com/stanfordnlp/dspy/pull/8389
Remove unused postprocess of param name by @TomeHirata in https://github.com/stanfordnlp/dspy/pull/8387
Remove experimental module by @TomeHirata in https://github.com/stanfordnlp/dspy/pull/8391
Remove commented out assertions file by @TomeHirata in https://github.com/stanfordnlp/dspy/pull/8388
Clean up unnecessary ruff exclude by @chenmoneygithub in https://github.com/stanfordnlp/dspy/pull/8399
Remove commented out old dotdict by @TomeHirata in https://github.com/stanfordnlp/dspy/pull/8401
Remove branch installation instruction by @TomeHirata in https://github.com/stanfordnlp/dspy/pull/8404
Remove dspy.settings related to dspy.Assertion by @chenmoneygithub in https://github.com/stanfordnlp/dspy/pull/8397
Remove unnecessary pre-commit exclusion by @chenmoneygithub in https://github.com/stanfordnlp/dspy/pull/8405
Rename modules to module by @TomeHirata in https://github.com/stanfordnlp/dspy/pull/8407
Move internal_dspy outside dspy module by @TomeHirata in https://github.com/stanfordnlp/dspy/pull/8400
Remove aws extra dep group by @TomeHirata in https://github.com/stanfordnlp/dspy/pull/8412
Move dsp/metrics into evaluate/metrics by @TomeHirata in https://github.com/stanfordnlp/dspy/pull/8402
Fix signature input type by @TomeHirata in https://github.com/stanfordnlp/dspy/pull/8413
Disable doc-push on forked repo by @chenmoneygithub in https://github.com/stanfordnlp/dspy/pull/8415
compute cache key once by @poudro in https://github.com/stanfordnlp/dspy/pull/8394
Add CLAUDE.local.md to .gitignore by @TomeHirata in https://github.com/stanfordnlp/dspy/pull/8420
Remove datasets installation from the Getting Started I by @chenmoneygithub in https://github.com/stanfordnlp/dspy/pull/8418
Add gemini to LM provider by @chenmoneygithub in https://github.com/stanfordnlp/dspy/pull/8417
change the default model to llama-4 for databricks provider by @chenmoneygithub in https://github.com/stanfordnlp/dspy/pull/8414
Move litellm cache testing under tests/client and remove unnecessary tests by @chenmoneygithub in https://github.com/stanfordnlp/dspy/pull/8396
Fix the error that status message streaming was blocking by @chenmoneygithub in https://github.com/stanfordnlp/dspy/pull/8432
Add real world tutorial for email extraction by @TomeHirata in https://github.com/stanfordnlp/dspy/pull/8426
Document comparison operations of dspy.Prediction by @TomeHirata in https://github.com/stanfordnlp/dspy/pull/8437
Drop Python 3.9 support by @TomeHirata in https://github.com/stanfordnlp/dspy/pull/8456
Add support for PEP 604 union types in inline signatures by @erandeutsch in https://github.com/stanfordnlp/dspy/pull/8449
Fix Lint by @TomeHirata in https://github.com/stanfordnlp/dspy/pull/8458
Update lockfile by @TomeHirata in https://github.com/stanfordnlp/dspy/pull/8459
Typo fix by @chenmoneygithub in https://github.com/stanfordnlp/dspy/pull/8462

Documentation

[update docs] init gsm8k = GSM8K() by @codingDuan in https://github.com/stanfordnlp/dspy/pull/8363
Add missing hooks to the tutorial of observability by @chenmoneygithub in https://github.com/stanfordnlp/dspy/pull/8368
Add a tutorial on customizing modules by @chenmoneygithub in https://github.com/stanfordnlp/dspy/pull/8370
Update the version to 3.0.0 in model saving doc by @TomeHirata in https://github.com/stanfordnlp/dspy/pull/8409
Automatic doc update by @chenmoneygithub in https://github.com/stanfordnlp/dspy/pull/8476
Fix mkdoc warnings by @TomeHirata in https://github.com/stanfordnlp/dspy/pull/8410
Expand sidenav items by default by @TomeHirata in https://github.com/stanfordnlp/dspy/pull/8411
Add real world example with yahoo finance Langchain tool by @TomeHirata in https://github.com/stanfordnlp/dspy/pull/8428
Add memory agent tutorial by @TomeHirata in https://github.com/stanfordnlp/dspy/pull/8427
Add real-world example overview page by @TomeHirata in https://github.com/stanfordnlp/dspy/pull/8442
Remove unsupported options of Plugin 'material/search' by @TomeHirata in https://github.com/stanfordnlp/dspy/pull/8423
Relax configure allowance in async tasks by @chenmoneygithub in https://github.com/stanfordnlp/dspy/pull/8444
Add tutorial for text based game by @TomeHirata in https://github.com/stanfordnlp/dspy/pull/8451
Add a tutorial for generating a code example from doc by @TomeHirata in https://github.com/stanfordnlp/dspy/pull/8450
Add llms.txt generation tutorial by @TomeHirata in https://github.com/stanfordnlp/dspy/pull/8421

New Contributors

@codingDuan made their first contribution in https://github.com/stanfordnlp/dspy/pull/8363
@Hangzhi made their first contribution in https://github.com/stanfordnlp/dspy/pull/8395
@poudro made their first contribution in https://github.com/stanfordnlp/dspy/pull/8394

Full Changelog: https://github.com/stanfordnlp/dspy/compare/3.0.0b1...3.0.0b2

Open source →

3.0.0b111 Jun 2025pre-releaseBreaking

A cleaner release note to follow. The only breaking change to be aware of in 3.0 is just #8073 for unmaintained retriever integration (should affect a…

What's Changed

A cleaner release note to follow. The only breaking change to be aware of in 3.0 is just #8073 for unmaintained retriever integration (should affect almost no one, and easy to migrate to custom code for those affected).

Fix Pydantic v2 deprecation warning in json_adapter by @brishin in https://github.com/stanfordnlp/dspy/pull/8263
Enable CI testing for all supported python versions by @chenmoneygithub in https://github.com/stanfordnlp/dspy/pull/8321
Fix the custom type extraction in dspy.BaseType by @chenmoneygithub in https://github.com/stanfordnlp/dspy/pull/8320
Add global max_errors setting by @okhat in https://github.com/stanfordnlp/dspy/pull/8319
Wrap langchain tool code example by asyncio runner by @chenmoneygithub in https://github.com/stanfordnlp/dspy/pull/8322
add more permission capabilities to PythonInterpreter by @arnavsinghvi11 in https://github.com/stanfordnlp/dspy/pull/8296
Fix logging configuration to prevent OpenTelemetry handler conflicts by @dmavrommatis in https://github.com/stanfordnlp/dspy/pull/8269
restore audio inspect_history by @arnavsinghvi11 in https://github.com/stanfordnlp/dspy/pull/8336
Standardize coding style in DSPy by @chenmoneygithub in https://github.com/stanfordnlp/dspy/pull/7885
Fix lint failures by @chenmoneygithub in https://github.com/stanfordnlp/dspy/pull/8337
Prompt users to run pre-commit when detecting ruff failures by @chenmoneygithub in https://github.com/stanfordnlp/dspy/pull/8338
refactoring audio_format completely by @arnavsinghvi11 in https://github.com/stanfordnlp/dspy/pull/8349
Add docstring for dspy.ReAct by @chenmoneygithub in https://github.com/stanfordnlp/dspy/pull/8334
Allow tool async to sync conversion by @chenmoneygithub in https://github.com/stanfordnlp/dspy/pull/8332
Fix missing [[ ## completed ## ]] in history and fewshot example by @chenmoneygithub in https://github.com/stanfordnlp/dspy/pull/8340
Fix usage tracking when None exists as value by @chenmoneygithub in https://github.com/stanfordnlp/dspy/pull/8339
Remove unused GRPO endpoint by @Ziems in https://github.com/stanfordnlp/dspy/pull/8354
update the MLflow tracing guide by @chenmoneygithub in https://github.com/stanfordnlp/dspy/pull/8353
Add xml adapter by @chenmoneygithub in https://github.com/stanfordnlp/dspy/pull/8358
Merge async settings change into main by @chenmoneygithub in https://github.com/stanfordnlp/dspy/pull/8361
Remove community retrievers by @TomeHirata in https://github.com/stanfordnlp/dspy/pull/8073

New Contributors

@brishin made their first contribution in https://github.com/stanfordnlp/dspy/pull/8263
@dmavrommatis made their first contribution in https://github.com/stanfordnlp/dspy/pull/8269

Full Changelog: https://github.com/stanfordnlp/dspy/compare/2.6.27...3.0.0b1

Open source →

2.6.252 Jun 2025withdrawn

Provide a standard base class for creating custom Signature field type by @chenmoneygithub in https://github.com/stanfordnlp/dspy/pull/8217

What's Changed

Core

Provide a standard base class for creating custom Signature field type by @chenmoneygithub in https://github.com/stanfordnlp/dspy/pull/8217
dspy.Audio by @arnavsinghvi11 in https://github.com/stanfordnlp/dspy/pull/8214
Fix audio attr name by @chenmoneygithub in https://github.com/stanfordnlp/dspy/pull/8241
Fix ReinforceJob LM reference by @okhat in https://github.com/stanfordnlp/dspy/pull/8249
Support python 3.13 by @TomeHirata in https://github.com/stanfordnlp/dspy/pull/8255
Avoid importing optuna in dspy import by @TomeHirata in https://github.com/stanfordnlp/dspy/pull/8258
Support custom imported module serialization with cloudpickle by @erandeutsch in https://github.com/stanfordnlp/dspy/pull/8286
Support for Service Principal Auth for Databricks Retrieve with DSPy by @willsmithDB in https://github.com/stanfordnlp/dspy/pull/8293
Fix Module history initialization by @okhat in https://github.com/stanfordnlp/dspy/pull/8307
Add pytest-asyncio to deps list of testing before pypi by @chenmoneygithub in https://github.com/stanfordnlp/dspy/pull/8308

Modules

Add CodeAct module by @TomeHirata in https://github.com/stanfordnlp/dspy/pull/8222
Per module lm history by @chenmoneygithub in https://github.com/stanfordnlp/dspy/pull/8199
Streaming: support models that don't split stream chunks in tokens by @chenmoneygithub in https://github.com/stanfordnlp/dspy/pull/8235
Support predicted output in DSPy by @chenmoneygithub in https://github.com/stanfordnlp/dspy/pull/8247
Bugfix: Ensure keys in both entities are merged by @estsauver in https://github.com/stanfordnlp/dspy/pull/8238
Fixes utf-8 formatting issues in optimization saves by @ItzAmirreza in https://github.com/stanfordnlp/dspy/pull/8272
Add langchain tool support by @TomeHirata in https://github.com/stanfordnlp/dspy/pull/8292

Misc

fix: use forked hotpotqa to bring dataset alive #8233 by @vincentkoc in https://github.com/stanfordnlp/dspy/pull/8234
fix(tests): use temp file for dataset by @estsauver in https://github.com/stanfordnlp/dspy/pull/8237
feat(dspy): custom type resolution in Signatures by @isaacbmiller in https://github.com/stanfordnlp/dspy/pull/8232
Remove dspy/.internal_dspyai/dist/ produced in the pipeline by @TomeHirata in https://github.com/stanfordnlp/dspy/pull/8240
Fix DataLoader input key bug by @okhat in https://github.com/stanfordnlp/dspy/pull/8248
Run tests with extra dependencies separately by @TomeHirata in https://github.com/stanfordnlp/dspy/pull/8246
Ensure dspy.Image allows gs://image_urls from Google Cloud Platform (GCP) by @dimroc in https://github.com/stanfordnlp/dspy/pull/8267
Fix the history related error of CodeAct by @TomeHirata in https://github.com/stanfordnlp/dspy/pull/8300

New Contributors

@vincentkoc made their first contribution in https://github.com/stanfordnlp/dspy/pull/8234
@estsauver made their first contribution in https://github.com/stanfordnlp/dspy/pull/8237
@jmho made their first contribution in https://github.com/stanfordnlp/dspy/pull/8229
@JHMuir made their first contribution in https://github.com/stanfordnlp/dspy/pull/8168
@neilbhutada made their first contribution in https://github.com/stanfordnlp/dspy/pull/8250
@carsonkahn-external made their first contribution in https://github.com/stanfordnlp/dspy/pull/8254
@dimroc made their first contribution in https://github.com/stanfordnlp/dspy/pull/8267
@erandeutsch made their first contribution in https://github.com/stanfordnlp/dspy/pull/8286
@willsmithDB made their first contribution in https://github.com/stanfordnlp/dspy/pull/8293

Full Changelog: https://github.com/stanfordnlp/dspy/compare/2.6.24...2.6.25

Open source →

dspy-ai

Release timeline

Releases

DSPy 3.4.0

Highlights

Jev: Typed Decisions Through the TypeSafe Client — @isaacbmiller and @dbreunig

ReAnchor Calibrates Decisions Against Your Metric — @isaacbmiller and @dbreunig

Native LM Engines and Custom HTTP Providers — @MaximeRivest

LocalInterpreter: Persistent CPython for Trusted Code — @isaacbmiller

Async ReActV2 and Custom Flex Code Proposals

Documentation Migrates to Zensical — @isaacbmiller

Versioned Documentation — @isaacbmiller

API and Compatibility Changes

RLM Call-Time Overrides Now Take a Keyword-Only Interpreter Factory

The Experimental 3.3 LM Types Are Replaced Now

Legacy LM Interfaces Are Deprecated Until the 3.5 Cutoff

Engine Behavior, Costs, and Saved State

Other Compatibility Notes

Full PR List

Jev, Decision Types, and Calibration

Language Models and Engines

Agents, Tools, and Interpreters

Optimization, Evaluation, Retrieval, and Usage

Adapters, Streaming, Imports, and Caching

Documentation

Dependencies, CI, and Release Engineering

Contributors

DSPy 3.4.0 Beta 1

Highlights

Native LM Engines and a New Custom-Backend Interface — @MaximeRivest

LocalInterpreter: Persistent CPython for Trusted Code — @isaacbmiller

Async ReActV2 and Explicit Final-Output Failures — @isaacbmiller

Custom Flex Code Proposals and More Reliable GEPA Evaluation — @dbreunig

API and Compatibility Changes

The Experimental 3.3 LM Types Are Replaced Now

Legacy LM Integrations Are Deprecated for Removal in 3.5

Native Multi-Answer Calls, Retries, and Streaming

Other Compatibility Changes

Full PR List

Language Models and Engines

Agents, Tools, and Interpreters

Optimization, Evaluation, and Examples

Adapters, Streaming, and Batching

Documentation

Dependencies, CI, and Release Engineering

Contributors

DSPy 3.3.1

Highlights

PythonInterpreter: Managed Runtime, Hardening, and Lifecycle Visibility

Installation, isolation, and execution integrity

Observability and agent integration

Typing, serialization, and compatibility details

Faster Multi-Proposal GEPA Optimization

More Reliable Structured Adapter Outputs

MCP SDK v2 Compatibility and Structured Results

API and Compatibility Changes

CodeAct and ProgramOfThought Deprecation

Resource Download Timeouts

Typed Interpreter and ReAct Errors

Additional Fixes

Full PR List

GEPA and Optimizers

Callbacks and Parallel Execution

Adapters, Tools, and MCP

Agents, Errors, and Code Execution

Datasets

Documentation

Testing, CI, Dependencies, and Release Engineering

Contributors

DSPy 3.3.0

Highlights

Flex Optimizes Program Structure, Not Just Prompts — @michaelisaac-dev

ReActV2 and Native Tool-Calling History - @isaacbmiller

Typed, Provider-Neutral LM Boundary - @MaximeRivest

BaseLM Runtime, Save/Load, Errors, and LiteLLM Decoupling - @MaximeRivest

LM and Responses API Updates Since 3.3.0b1 - @MaximeRivest, @isaacbmiller

API Changes

Breaking Changes

Resource Construction and Validation No Longer Perform Implicit I/O

numpy Is Now Optional

`numpy` Is Now Optional

GEPA Result Shapes Changed With `gepa[dspy]==0.1.1`

`RLM.max_iterations` Is Now `RLM.max_iters`

`ToolCalls` Uses DSPy's Native Serialized Shape

Direct `BaseLM` Defaults and Copy Semantics Changed

`numpy` Is Now Optional

GEPA Result Shapes Changed With `gepa[dspy]==0.1.1`