Merge branch 'main' into feature/audio_utils

Author: pretbc

docs/docs/index.md

@@ -10,6 +10,7 @@ hide:
 
 # _Programming_—not prompting—_LMs_
 
+[![PyPI Downloads](https://static.pepy.tech/badge/dspy/month)](https://pepy.tech/projects/dspy)
 
 DSPy is the framework for _programming—rather than prompting—language models_. It allows you to iterate fast on **building modular AI systems** and offers algorithms for **optimizing their prompts and weights**, whether you're building simple classifiers, sophisticated RAG pipelines, or Agent loops.
 

dspy/__init__.py

@@ -8,7 +8,7 @@
 
 from dspy.evaluate import Evaluate  # isort: skip
 from dspy.clients import *  # isort: skip
-from dspy.adapters import Adapter, ChatAdapter, JSONAdapter, Image, Audio  # isort: skip
+from dspy.adapters import Adapter, ChatAdapter, JSONAdapter, Image, History, Audio  # isort: skip
 from dspy.utils.logging_utils import configure_dspy_loggers, disable_logging, enable_logging
 from dspy.utils.asyncify import asyncify
 from dspy.utils.saving import load
@@ -26,11 +26,4 @@
 
 BootstrapRS = BootstrapFewShotWithRandomSearch
 
-from .__metadata__ import (
-    __name__,
-    __version__,
-    __description__,
-    __url__,
-    __author__,
-    __author_email__
-)
+from .__metadata__ import __name__, __version__, __description__, __url__, __author__, __author_email__

dspy/__metadata__.py

@@ -1,7 +1,7 @@
 #replace_package_name_marker
 __name__="dspy"
 #replace_package_version_marker
-__version__="2.6.5"
+__version__="2.6.9rc1"
 __description__="DSPy"
 __url__="https://github.com/stanfordnlp/dspy"
 __author__="Omar Khattab"

dspy/adapters/__init__.py

@@ -3,13 +3,15 @@
 from dspy.adapters.json_adapter import JSONAdapter
 from dspy.adapters.image_utils import Image, encode_image, is_image
 from dspy.adapters.audio_utils import Audio, encode_audio, is_audio
+from dspy.adapters.types import History
 from dspy.adapters.media_utils import try_expand_media_tags
 
 __all__ = [
     'Adapter',
     'ChatAdapter',
     'JSONAdapter',
     'Image',
+    'History',
     'Audio',
     'encode_image',
     'encode_audio',

dspy/adapters/base.py

@@ -2,6 +2,7 @@
 
 from litellm import ContextWindowExceededError
 
+from dspy.adapters.types import History
 from dspy.utils.callback import with_callbacks
 
 
@@ -32,12 +33,15 @@ def __call__(self, lm, lm_kwargs, signature, demos, inputs):
 
                 value = self.parse(signature, output)
 
-                assert set(value.keys()) == set(signature.output_fields.keys()), \
-                    f"Expected {signature.output_fields.keys()} but got {value.keys()}"
-                
+                if set(value.keys()) != set(signature.output_fields.keys()):
+                    raise ValueError(
+                        "Parsed output fields do not match signature output fields. "
+                        f"Expected: {set(signature.output_fields.keys())}, Got: {set(value.keys())}"
+                    )
+
                 if output_logprobs is not None:
                     value["logprobs"] = output_logprobs
-                
+
                 values.append(value)
 
             return values
@@ -46,18 +50,54 @@ def __call__(self, lm, lm_kwargs, signature, demos, inputs):
             if isinstance(e, ContextWindowExceededError):
                 # On context window exceeded error, we don't want to retry with a different adapter.
                 raise e
-            from .json_adapter import JSONAdapter
+            from dspy.adapters.json_adapter import JSONAdapter
+
             if not isinstance(self, JSONAdapter):
                 return JSONAdapter()(lm, lm_kwargs, signature, demos, inputs)
             raise e
 
     @abstractmethod
     def format(self, signature, demos, inputs):
-       raise NotImplementedError
+        raise NotImplementedError
 
     @abstractmethod
     def parse(self, signature, completion):
-       raise NotImplementedError
+        raise NotImplementedError
 
     def format_finetune_data(self, signature, demos, inputs, outputs):
         raise NotImplementedError
+
+    def format_turn(self, signature, values, role, incomplete=False, is_conversation_history=False):
+        pass
+
+    def format_conversation_history(self, signature, inputs):
+        history_field_name = None
+        for name, field in signature.input_fields.items():
+            if field.annotation == History:
+                history_field_name = name
+                break
+
+        if history_field_name is None:
+            return []
+
+        # In order to format the conversation history, we need to remove the history field from the signature.
+        signature_without_history = signature.delete(history_field_name)
+        conversation_history = inputs[history_field_name].messages if history_field_name in inputs else None
+
+        if conversation_history is None:
+            return []
+
+        messages = []
+        for message in conversation_history:
+            messages.append(
+                self.format_turn(signature_without_history, message, role="user", is_conversation_history=True)
+            )
+            messages.append(
+                self.format_turn(signature_without_history, message, role="assistant", is_conversation_history=True)
+            )
+
+        inputs_copy = dict(inputs)
+        del inputs_copy[history_field_name]
+
+        messages.append(self.format_turn(signature_without_history, inputs_copy, role="user"))
+        return messages

dspy/adapters/chat_adapter.py

@@ -11,6 +11,7 @@
 from pydantic.fields import FieldInfo
 
 from dspy.adapters.base import Adapter
+from dspy.adapters.types.history import History
 from dspy.adapters.utils import format_field_value, get_annotation_name, parse_value
 from dspy.signatures.field import OutputField
 from dspy.signatures.signature import Signature, SignatureMeta
@@ -46,15 +47,23 @@ def format(self, signature: Signature, demos: list[dict[str, Any]], inputs: dict
         ]
 
         demos = incomplete_demos + complete_demos
-
         prepared_instructions = prepare_instructions(signature)
         messages.append({"role": "system", "content": prepared_instructions})
+
+        # Add the few-shot examples
         for demo in demos:
-            messages.append(format_turn(signature, demo, role="user", incomplete=demo in incomplete_demos))
-            messages.append(format_turn(signature, demo, role="assistant", incomplete=demo in incomplete_demos))
+            messages.append(self.format_turn(signature, demo, role="user", incomplete=demo in incomplete_demos))
+            messages.append(self.format_turn(signature, demo, role="assistant", incomplete=demo in incomplete_demos))
+
+        # Add the chat history after few-shot examples
+        if any(field.annotation == History for field in signature.input_fields.values()):
+            messages.extend(self.format_conversation_history(signature, inputs))
+        else:
+            messages.append(self.format_turn(signature, inputs, role="user"))
 
         messages.append(format_turn(signature, inputs, role="user"))
         messages = try_expand_media_tags(messages)
+
         return messages
 
     def parse(self, signature, completion):
@@ -92,7 +101,7 @@ def format_finetune_data(self, signature, demos, inputs, outputs):
         # Add the assistant message
         role = "assistant"
         incomplete = False
-        assistant_message = format_turn(signature, outputs, role, incomplete)
+        assistant_message = self.format_turn(signature, outputs, role, incomplete)
         messages.append(assistant_message)
 
         # Wrap the messages in a dictionary with a "messages" key
@@ -108,6 +117,9 @@ def format_fields(self, signature, values, role):
         }
         return format_fields(fields_with_values)
 
+    def format_turn(self, signature, values, role, incomplete=False, is_conversation_history=False):
+        return format_turn(signature, values, role, incomplete, is_conversation_history)
+
 
 def format_fields(fields_with_values: Dict[FieldInfoWithName, Any]) -> str:
     """
@@ -129,7 +141,7 @@ def format_fields(fields_with_values: Dict[FieldInfoWithName, Any]) -> str:
     return "\n\n".join(output).strip()
 
 
-def format_turn(signature, values, role, incomplete=False):
+def format_turn(signature, values, role, incomplete=False, is_conversation_history=False):
     """
     Constructs a new message ("turn") to append to a chat thread. The message is carefully formatted
     so that it can instruct an LLM to generate responses conforming to the specified DSPy signature.
@@ -140,24 +152,31 @@ def format_turn(signature, values, role, incomplete=False):
             that should be included in the message.
         role: The role of the message, which can be either "user" or "assistant".
         incomplete: If True, indicates that output field values are present in the set of specified
-            ``values``. If False, indicates that ``values`` only contains input field values.
+            `values`. If False, indicates that `values` only contains input field values. Only used if
+            `is_conversation_history` is False.
+        is_conversation_history: If True, indicates that the message is part of the chat history, otherwise
+            it is a demo (few-shot example).
 
     Returns:
         A chat message that can be appended to a chat thread. The message contains two string fields:
-        ``role`` ("user" or "assistant") and ``content`` (the message text).
+        `role` ("user" or "assistant") and `content` (the message text).
     """
     if role == "user":
         fields = signature.input_fields
-        message_prefix = (
-            "This is an example of the task, though some input or output fields are not supplied." if incomplete else ""
-        )
+        if incomplete and not is_conversation_history:
+            message_prefix = "This is an example of the task, though some input or output fields are not supplied."
+        else:
+            message_prefix = ""
     else:
-        # Add the completed field for the assistant turn
-        fields = {**signature.output_fields, BuiltInCompletedOutputFieldInfo.name: BuiltInCompletedOutputFieldInfo.info}
-        values = {**values, BuiltInCompletedOutputFieldInfo.name: ""}
+        # Add the completed field or chat history for the assistant turn
+        fields = {**signature.output_fields}
+        values = {**values}
         message_prefix = ""
+        if not is_conversation_history:
+            fields.update({BuiltInCompletedOutputFieldInfo.name: BuiltInCompletedOutputFieldInfo.info})
+            values.update({BuiltInCompletedOutputFieldInfo.name: ""})
 
-    if not incomplete and not set(values).issuperset(fields.keys()):
+    if not incomplete and not is_conversation_history and not set(values).issuperset(fields.keys()):
         raise ValueError(f"Expected {fields.keys()} but got {values.keys()}")
 
     messages = []
@@ -166,7 +185,12 @@ def format_turn(signature, values, role, incomplete=False):
 
     field_messages = format_fields(
         {
-            FieldInfoWithName(name=k, info=v): values.get(k, "Not supplied for this particular example.")
+            FieldInfoWithName(name=k, info=v): values.get(
+                k,
+                "Not supplied for this conversation history message. "
+                if is_conversation_history
+                else "Not supplied for this particular example. ",
+            )
             for k, v in fields.items()
         },
     )

dspy/adapters/json_adapter.py

@@ -15,7 +15,8 @@
 from dspy.adapters.base import Adapter
 from dspy.adapters.image_utils import Image
 from dspy.adapters.audio_utils import Audio
-from dspy.adapters.utils import parse_value, format_field_value, get_annotation_name, serialize_for_json
+from dspy.adapters.types.history import History
+from dspy.adapters.utils import format_field_value, get_annotation_name, parse_value, serialize_for_json
 from dspy.signatures.signature import SignatureMeta
 from dspy.signatures.utils import get_dspy_field_type
 
@@ -83,10 +84,14 @@ def format(self, signature, demos, inputs):
         messages.append({"role": "system", "content": prepare_instructions(signature)})
 
         for demo in demos:
-            messages.append(format_turn(signature, demo, role="user", incomplete=demo in incomplete_demos))
-            messages.append(format_turn(signature, demo, role="assistant", incomplete=demo in incomplete_demos))
+            messages.append(self.format_turn(signature, demo, role="user", incomplete=demo in incomplete_demos))
+            messages.append(self.format_turn(signature, demo, role="assistant", incomplete=demo in incomplete_demos))
 
-        messages.append(format_turn(signature, inputs, role="user"))
+        # Add the chat history after few-shot examples
+        if any(field.annotation == History for field in signature.input_fields.values()):
+            messages.extend(self.format_conversation_history(signature, inputs))
+        else:
+            messages.append(self.format_turn(signature, inputs, role="user"))
 
         return messages
 
@@ -104,8 +109,8 @@ def parse(self, signature, completion):
 
         return fields
 
-    def format_turn(self, signature, values, role, incomplete=False):
-        return format_turn(signature, values, role, incomplete)
+    def format_turn(self, signature, values, role, incomplete=False, is_conversation_history=False):
+        return format_turn(signature, values, role, incomplete, is_conversation_history)
 
     def format_fields(self, signature, values, role):
         fields_with_values = {
@@ -164,7 +169,13 @@ def format_fields(role: str, fields_with_values: Dict[FieldInfoWithName, Any]) -
     return "\n\n".join(output).strip()
 
 
-def format_turn(signature: SignatureMeta, values: Dict[str, Any], role, incomplete=False) -> Dict[str, str]:
+def format_turn(
+    signature: SignatureMeta,
+    values: Dict[str, Any],
+    role,
+    incomplete=False,
+    is_conversation_history=False,
+) -> Dict[str, str]:
     """
     Constructs a new message ("turn") to append to a chat thread. The message is carefully formatted
     so that it can instruct an LLM to generate responses conforming to the specified DSPy signature.
@@ -175,7 +186,10 @@ def format_turn(signature: SignatureMeta, values: Dict[str, Any], role, incomple
             that should be included in the message.
         role: The role of the message, which can be either "user" or "assistant".
         incomplete: If True, indicates that output field values are present in the set of specified
-            ``values``. If False, indicates that ``values`` only contains input field values.
+            `values`. If False, indicates that `values` only contains input field values. Only
+            relevant if `is_conversation_history` is False.
+        is_conversation_history: If True, indicates that the message is part of a chat history instead of a
+            few-shot example.
     Returns:
         A chat message that can be appended to a chat thread. The message contains two string fields:
         ``role`` ("user" or "assistant") and ``content`` (the message text).
@@ -184,25 +198,29 @@ def format_turn(signature: SignatureMeta, values: Dict[str, Any], role, incomple
 
     if role == "user":
         fields: Dict[str, FieldInfo] = signature.input_fields
-        if incomplete:
+        if incomplete and not is_conversation_history:
             content.append("This is an example of the task, though some input or output fields are not supplied.")
     else:
         fields: Dict[str, FieldInfo] = signature.output_fields
 
-    if not incomplete:
+    if not incomplete and not is_conversation_history:
+        # For complete few-shot examples, ensure that the values contain all the fields.
         field_names: KeysView = fields.keys()
         if not set(values).issuperset(set(field_names)):
             raise ValueError(f"Expected {field_names} but got {values.keys()}")
 
-    formatted_fields = format_fields(
-        role=role,
-        fields_with_values={
-            FieldInfoWithName(name=field_name, info=field_info): values.get(
-                field_name, "Not supplied for this particular example."
+    fields_with_values = {}
+    for field_name, field_info in fields.items():
+        if is_conversation_history:
+            fields_with_values[FieldInfoWithName(name=field_name, info=field_info)] = values.get(
+                field_name, "Not supplied for this conversation history message. "
             )
-            for field_name, field_info in fields.items()
-        },
-    )
+        else:
+            fields_with_values[FieldInfoWithName(name=field_name, info=field_info)] = values.get(
+                field_name, "Not supplied for this particular example. "
+            )
+
+    formatted_fields = format_fields(role=role, fields_with_values=fields_with_values)
     content.append(formatted_fields)
 
     if role == "user":

dspy/adapters/types/__init__.py

@@ -0,0 +1,3 @@
+from dspy.adapters.types.history import History
+
+__all__ = ["History"]