Allow DSPy to use the native reasoning from models

dspy/__init__.py

@@ -6,7 +6,7 @@
 
 from dspy.evaluate import Evaluate  # isort: skip
 from dspy.clients import *  # isort: skip
-from dspy.adapters import Adapter, ChatAdapter, JSONAdapter, XMLAdapter, TwoStepAdapter, Image, Audio, History, Type, Tool, ToolCalls, Code  # isort: skip
+from dspy.adapters import Adapter, ChatAdapter, JSONAdapter, XMLAdapter, TwoStepAdapter, Image, Audio, History, Type, Tool, ToolCalls, Code, Reasoning  # isort: skip
 from dspy.utils.logging_utils import configure_dspy_loggers, disable_logging, enable_logging
 from dspy.utils.asyncify import asyncify
 from dspy.utils.syncify import syncify

dspy/adapters/__init__.py

@@ -2,7 +2,7 @@
 from dspy.adapters.chat_adapter import ChatAdapter
 from dspy.adapters.json_adapter import JSONAdapter
 from dspy.adapters.two_step_adapter import TwoStepAdapter
-from dspy.adapters.types import Audio, Code, History, Image, Tool, ToolCalls, Type
+from dspy.adapters.types import Audio, Code, History, Image, Reasoning, Tool, ToolCalls, Type
 from dspy.adapters.xml_adapter import XMLAdapter
 
 __all__ = [
@@ -18,4 +18,5 @@
     "TwoStepAdapter",
     "Tool",
     "ToolCalls",
+    "Reasoning",
 ]

dspy/adapters/base.py

@@ -6,6 +6,7 @@
 
 from dspy.adapters.types import History, Type
 from dspy.adapters.types.base_type import split_message_content_for_custom_types
+from dspy.adapters.types.reasoning import Reasoning
 from dspy.adapters.types.tool import Tool, ToolCalls
 from dspy.experimental import Citations
 from dspy.signatures.signature import Signature
@@ -16,10 +17,16 @@
 if TYPE_CHECKING:
     from dspy.clients.lm import LM
 
-_DEFAULT_NATIVE_RESPONSE_TYPES = [Citations]
+_DEFAULT_NATIVE_RESPONSE_TYPES = [Citations, Reasoning]
+
 
 class Adapter:
-    def __init__(self, callbacks: list[BaseCallback] | None = None, use_native_function_calling: bool = False, native_response_types: list[type[Type]] | None = None):
+    def __init__(
+        self,
+        callbacks: list[BaseCallback] | None = None,
+        use_native_function_calling: bool = False,
+        native_response_types: list[type[Type]] | None = None,
+    ):
         self.callbacks = callbacks or []
         self.use_native_function_calling = use_native_function_calling
         self.native_response_types = native_response_types or _DEFAULT_NATIVE_RESPONSE_TYPES
@@ -66,9 +73,14 @@ def _call_preprocess(
 
                 return signature_for_native_function_calling
 
-        # Handle custom types that use native response
+        # Handle custom types that use native LM features, e.g., reasoning, citations, etc.
         for name, field in signature.output_fields.items():
-            if isinstance(field.annotation, type) and issubclass(field.annotation, Type) and field.annotation in self.native_response_types:
+            if (
+                isinstance(field.annotation, type)
+                and issubclass(field.annotation, Type)
+                and field.annotation in self.native_response_types
+                and field.annotation.adapt_to_native_lm_feature(lm, lm_kwargs)
+            ):
                 signature = signature.delete(name)
 
         return signature
@@ -79,6 +91,7 @@ def _call_postprocess(
         original_signature: type[Signature],
         outputs: list[dict[str, Any]],
         lm: "LM",
+        lm_kwargs: dict[str, Any],
     ) -> list[dict[str, Any]]:
         values = []
 
@@ -117,7 +130,12 @@ def _call_postprocess(
 
             # Parse custom types that does not rely on the adapter parsing
             for name, field in original_signature.output_fields.items():
-                if isinstance(field.annotation, type) and issubclass(field.annotation, Type) and field.annotation in self.native_response_types:
+                if (
+                    isinstance(field.annotation, type)
+                    and issubclass(field.annotation, Type)
+                    and field.annotation in self.native_response_types
+                    and field.annotation.adapt_to_native_lm_feature(lm, lm_kwargs)
+                ):
                     value[name] = field.annotation.parse_lm_response(output)
 
             if output_logprobs:
@@ -139,7 +157,7 @@ def __call__(
         inputs = self.format(processed_signature, demos, inputs)
 
         outputs = lm(messages=inputs, **lm_kwargs)
-        return self._call_postprocess(processed_signature, signature, outputs, lm)
+        return self._call_postprocess(processed_signature, signature, outputs, lm, lm_kwargs)
 
     async def acall(
         self,
@@ -153,7 +171,7 @@ async def acall(
         inputs = self.format(processed_signature, demos, inputs)
 
         outputs = await lm.acall(messages=inputs, **lm_kwargs)
-        return self._call_postprocess(processed_signature, signature, outputs, lm)
+        return self._call_postprocess(processed_signature, signature, outputs, lm, lm_kwargs)
 
     def format(
         self,
@@ -404,7 +422,6 @@ def _get_tool_call_output_field_name(self, signature: type[Signature]) -> bool:
                 return name
         return None
 
-
     def format_conversation_history(
         self,
         signature: type[Signature],

dspy/adapters/types/__init__.py

@@ -3,6 +3,7 @@
 from dspy.adapters.types.code import Code
 from dspy.adapters.types.history import History
 from dspy.adapters.types.image import Image
+from dspy.adapters.types.reasoning import Reasoning
 from dspy.adapters.types.tool import Tool, ToolCalls
 
-__all__ = ["History", "Image", "Audio", "Type", "Tool", "ToolCalls", "Code"]
+__all__ = ["History", "Image", "Audio", "Type", "Tool", "ToolCalls", "Code", "Reasoning"]

dspy/adapters/types/base_type.py

@@ -70,6 +70,11 @@ def serialize_model(self):
             )
         return formatted
 
+    @classmethod
+    def adapt_to_native_lm_feature(cls, lm, lm_kwargs) -> bool:
+        """Check whether the custom type is natively supported by the LM and adapt to the native feature if possible."""
+        return False
+
     @classmethod
     def is_streamable(cls) -> bool:
         """Whether the custom type is streamable."""
@@ -88,7 +93,6 @@ def parse_stream_chunk(cls, chunk: ModelResponseStream) -> Optional["Type"]:
         """
         return None
 
-
     @classmethod
     def parse_lm_response(cls, response: str | dict[str, Any]) -> Optional["Type"]:
         """Parse a LM response into the custom type.
@@ -101,6 +105,7 @@ def parse_lm_response(cls, response: str | dict[str, Any]) -> Optional["Type"]:
         """
         return None
 
+
 def split_message_content_for_custom_types(messages: list[dict[str, Any]]) -> list[dict[str, Any]]:
     """Split user message content into a list of content blocks.
 

dspy/adapters/types/citation.py

@@ -54,6 +54,7 @@ class AnswerWithSources(Signature):
 
     class Citation(Type):
         """Individual citation with character location information."""
+
         type: str = "char_location"
         cited_text: str
         document_index: int
@@ -73,7 +74,7 @@ def format(self) -> dict[str, Any]:
                 "cited_text": self.cited_text,
                 "document_index": self.document_index,
                 "start_char_index": self.start_char_index,
-                "end_char_index": self.end_char_index
+                "end_char_index": self.end_char_index,
             }
 
             if self.document_title:
@@ -134,9 +135,7 @@ def validate_input(cls, data: Any):
             return data
 
         # Handle case where data is a list of dicts with citation info
-        if isinstance(data, list) and all(
-            isinstance(item, dict) and "cited_text" in item for item in data
-        ):
+        if isinstance(data, list) and all(isinstance(item, dict) and "cited_text" in item for item in data):
             return {"citations": [cls.Citation(**item) for item in data]}
 
         # Handle case where data is a dict
@@ -147,8 +146,7 @@ def validate_input(cls, data: Any):
                 if isinstance(citations_data, list):
                     return {
                         "citations": [
-                            cls.Citation(**item) if isinstance(item, dict) else item
-                            for item in citations_data
+                            cls.Citation(**item) if isinstance(item, dict) else item for item in citations_data
                         ]
                     }
             elif "cited_text" in data:
@@ -169,6 +167,10 @@ def __getitem__(self, index):
         """Allow indexing into citations."""
         return self.citations[index]
 
+    @classmethod
+    def adapt_to_native_lm_feature(cls, lm, lm_kwargs) -> bool:
+        return lm.model.startswith("anthropic/")
+
     @classmethod
     def is_streamable(cls) -> bool:
         """Whether the Citations type is streamable."""
@@ -197,7 +199,6 @@ def parse_stream_chunk(cls, chunk) -> Optional["Citations"]:
             pass
         return None
 
-
     @classmethod
     def parse_lm_response(cls, response: str | dict[str, Any]) -> Optional["Citations"]:
         """Parse a LM response into Citations.

dspy/adapters/types/reasoning.py

@@ -0,0 +1,79 @@
+from typing import Any, Optional
+
+import litellm
+import pydantic
+
+from dspy.adapters.types.base_type import Type
+
+
+class Reasoning(Type):
+    """Reasoning type in DSPy.
+
+    This type is useful when you want the DSPy output to include the reasoning of the LM. We build this type so that
+    DSPy can support the reasoning model and non-reasoning model with the same code.
+
+    This is a str-like type, you can convert a string directly to a Reasoning object, and from DSPy adapters'
+    perspective, `Reasoning` is treated as a string.
+    """
+
+    content: str
+
+    def format(self):
+        return f"{self.content}"
+
+    @pydantic.model_validator(mode="before")
+    @classmethod
+    def validate_input(cls, data: Any):
+        if isinstance(data, cls):
+            return data
+
+        if isinstance(data, str):
+            return {"content": data}
+
+        if isinstance(data, dict):
+            if "content" not in data:
+                raise ValueError("`content` field is required for `dspy.Reasoning`")
+            if not isinstance(data["content"], str):
+                raise ValueError(f"`content` field must be a string, but received type: {type(data['content'])}")
+            return {"content": data["content"]}
+
+        raise ValueError(f"Received invalid value for `dspy.Reasoning`: {data}")
+
+    @classmethod
+    def adapt_to_native_lm_feature(cls, lm, lm_kwargs) -> bool:
+        if not litellm.supports_reasoning(lm.model):
+            return False
+
+        reasoning_effort = "unspecified"
+        if "reasoning_effort" in lm_kwargs:
+            # `lm_kwargs` overrides `lm.kwargs`
+            reasoning_effort = lm_kwargs["reasoning_effort"]
+        elif "reasoning_effort" in lm.kwargs:
+            reasoning_effort = lm.kwargs["reasoning_effort"]
+
+        if reasoning_effort is None:
+            # If users explicitly set `reasoning_effort` to None, we don't enable native reasoning
+            return False
+
+        # Turn on the native reasoning
+        lm_kwargs["reasoning_effort"] = "low"
+        return True
+
+    @classmethod
+    def parse_lm_response(cls, response: str | dict[str, Any]) -> Optional["Reasoning"]:
+        """Parse the LM response into a Reasoning object."""
+        if "reasoning_content" in response:
+            return Reasoning(content=response["reasoning_content"])
+        return None
+
+    def __repr__(self) -> str:
+        return f"{self.content!r}"
+
+    def __str__(self) -> str:
+        return self.content
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, Reasoning):
+            return self.content == other.content
+        if isinstance(other, str):
+            return self.content == other

dspy/adapters/utils.py

@@ -12,6 +12,7 @@
 from pydantic.fields import FieldInfo
 
 from dspy.adapters.types.base_type import Type as DspyType
+from dspy.adapters.types.reasoning import Reasoning
 from dspy.signatures.utils import get_dspy_field_type
 
 
@@ -84,7 +85,7 @@ def move_type_to_front(d):
 def translate_field_type(field_name, field_info):
     field_type = field_info.annotation
 
-    if get_dspy_field_type(field_info) == "input" or field_type is str:
+    if get_dspy_field_type(field_info) == "input" or field_type is str or field_type is Reasoning:
         desc = ""
     elif field_type is bool:
         desc = "must be True or False"
@@ -190,6 +191,8 @@ def get_annotation_name(annotation):
     origin = get_origin(annotation)
     args = get_args(annotation)
     if origin is None:
+        if annotation is Reasoning:
+            return "str"
         if hasattr(annotation, "__name__"):
             return annotation.__name__
         else:

dspy/clients/base_lm.py

@@ -179,6 +179,10 @@ def _process_completion(self, response, merged_kwargs):
         for c in response.choices:
             output = {}
             output["text"] = c.message.content if hasattr(c, "message") else c["text"]
+
+            if hasattr(c, "message") and hasattr(c.message, "reasoning_content") and c.message.reasoning_content:
+                output["reasoning_content"] = c.message.reasoning_content
+
             if merged_kwargs.get("logprobs"):
                 output["logprobs"] = c.logprobs if hasattr(c, "logprobs") else c["logprobs"]
             if hasattr(c, "message") and getattr(c.message, "tool_calls", None):
@@ -194,7 +198,6 @@ def _process_completion(self, response, merged_kwargs):
         if all(len(output) == 1 for output in outputs):
             # Return a list if every output only has "text" key
             outputs = [output["text"] for output in outputs]
-
         return outputs
 
     def _extract_citations_from_response(self, choice):

dspy/clients/lm.py

@@ -456,4 +456,8 @@ def _convert_chat_request_to_responses_request(request: dict[str, Any]):
             elif isinstance(c, list):
                 content_blocks.extend(c)
         request["input"] = [{"role": msg.get("role", "user"), "content": content_blocks}]
+    # Convert reasoning_effort to reasoning format supported by the Responses API
+    if "reasoning_effort" in request:
+        effort = request.pop("reasoning_effort")
+        request["reasoning"] = {"effort": effort, "summary": "auto"}
     return request

dspy/predict/chain_of_thought.py

@@ -1,36 +1,36 @@
+import logging
 from typing import Any
 
-from pydantic.fields import FieldInfo
-
 import dspy
 from dspy.primitives.module import Module
+from dspy.signatures.field import OutputField
 from dspy.signatures.signature import Signature, ensure_signature
 
+logger = logging.getLogger(__name__)
+
 
 class ChainOfThought(Module):
     def __init__(
         self,
         signature: str | type[Signature],
-        rationale_field: FieldInfo | None = None,
-        rationale_field_type: type = str,
         **config: dict[str, Any],
     ):
         """
         A module that reasons step by step in order to predict the output of a task.
 
         Args:
             signature (Type[dspy.Signature]): The signature of the module.
-            rationale_field (Optional[Union[dspy.OutputField, pydantic.fields.FieldInfo]]): The field that will contain the reasoning.
-            rationale_field_type (Type): The type of the rationale field.
             **config: The configuration for the module.
         """
         super().__init__()
         signature = ensure_signature(signature)
-        prefix = "Reasoning: Let's think step by step in order to"
-        desc = "${reasoning}"
-        rationale_field_type = rationale_field.annotation if rationale_field else rationale_field_type
-        rationale_field = rationale_field if rationale_field else dspy.OutputField(prefix=prefix, desc=desc)
-        extended_signature = signature.prepend(name="reasoning", field=rationale_field, type_=rationale_field_type)
+
+        if "rationale_field" in config or "rationale_field_type" in config:
+            logger.warning("`rationale_field` and `rationale_field_type` are deprecated, they are no-op now.")
+
+        from dspy.adapters.types.reasoning import Reasoning
+
+        extended_signature = signature.prepend(name="reasoning", field=OutputField(), type_=Reasoning)
         self.predict = dspy.Predict(extended_signature, **config)
 
     def forward(self, **kwargs):