Initial refactor. To Clean

Author: isaacbmiller

dspy/adapters/base.py

@@ -9,6 +9,7 @@
 from dspy.adapters.types.reasoning import Reasoning
 from dspy.adapters.types.tool import Tool, ToolCalls
 from dspy.experimental import Citations
+from dspy.signatures.field import InputField, OutputField
 from dspy.signatures.signature import Signature
 from dspy.utils.callback import BaseCallback, with_callbacks
 
@@ -474,6 +475,23 @@ def _get_tool_call_output_field_name(self, signature: type[Signature]) -> bool:
                 return name
         return None
 
+    def _serialize_kv_value(self, v: Any) -> Any:
+        """Safely serialize values for kv-mode formatting."""
+        if isinstance(v, (str, int, float, bool)) or v is None:
+            return v
+        try:
+            return str(v)
+        except Exception:
+            return f"<unserializable {type(v).__name__}>"
+
+    def _make_dynamic_signature_for_inputs(self, keys: list[str]) -> type[Signature]:
+        """Create a dynamic signature with input fields only (no instructions)."""
+        return Signature({k: InputField() for k in keys}, instructions="")
+
+    def _make_dynamic_signature_for_outputs(self, keys: list[str]) -> type[Signature]:
+        """Create a dynamic signature with output fields only (no instructions)."""
+        return Signature({k: OutputField() for k in keys}, instructions="")
+
     def format_conversation_history(
         self,
         signature: type[Signature],
@@ -483,6 +501,11 @@ def format_conversation_history(
         """Format the conversation history.
 
         This method formats the conversation history and the current input as multiturn messages.
+        Supports four modes:
+        - signature: Dict keys match signature input/output fields → user/assistant pairs
+        - kv: Nested {"input_fields": {...}, "output_fields": {...}} → user/assistant pairs
+        - dict: Arbitrary serializable kv pairs → all in single user message (default)
+        - raw: Direct LM messages with {"role": "user", "content": "..."} → passed through
 
         Args:
             signature: The DSPy signature for which to format the conversation history.
@@ -492,25 +515,50 @@ def format_conversation_history(
         Returns:
             A list of multiturn messages.
         """
-        conversation_history = inputs[history_field_name].messages if history_field_name in inputs else None
-
-        if conversation_history is None:
+        history = inputs.get(history_field_name)
+        if history is None:
             return []
 
         messages = []
-        for message in conversation_history:
-            messages.append(
-                {
+        for msg in history.messages:
+            mode = history._detect_mode(msg)
+
+            if mode == "raw":
+                messages.append(dict(msg))
+
+            elif mode == "kv":
+                if "input_fields" in msg:
+                    input_dict = {k: self._serialize_kv_value(v) for k, v in msg["input_fields"].items()}
+                    sig = self._make_dynamic_signature_for_inputs(list(input_dict.keys()))
+                    messages.append({
+                        "role": "user",
+                        "content": self.format_user_message_content(sig, input_dict),
+                    })
+                if "output_fields" in msg:
+                    output_dict = {k: self._serialize_kv_value(v) for k, v in msg["output_fields"].items()}
+                    sig = self._make_dynamic_signature_for_outputs(list(output_dict.keys()))
+                    messages.append({
+                        "role": "assistant",
+                        "content": self.format_assistant_message_content(sig, output_dict),
+                    })
+
+            elif mode == "signature":
+                messages.append({
                     "role": "user",
-                    "content": self.format_user_message_content(signature, message),
-                }
-            )
-            messages.append(
-                {
+                    "content": self.format_user_message_content(signature, msg),
+                })
+                messages.append({
                     "role": "assistant",
-                    "content": self.format_assistant_message_content(signature, message),
-                }
-            )
+                    "content": self.format_assistant_message_content(signature, msg),
+                })
+
+            else:  # dict mode (default) - all kv pairs go into single user message
+                serialized = {k: self._serialize_kv_value(v) for k, v in msg.items()}
+                sig = self._make_dynamic_signature_for_inputs(list(serialized.keys()))
+                messages.append({
+                    "role": "user",
+                    "content": self.format_user_message_content(sig, serialized),
+                })
 
         # Remove the history field from the inputs
         del inputs[history_field_name]

dspy/adapters/types/history.py

@@ -1,25 +1,47 @@
-from typing import Any
+from typing import Any, Literal
 
 import pydantic
 
 
 class History(pydantic.BaseModel):
     """Class representing the conversation history.
 
-    The conversation history is a list of messages, each message entity should have keys from the associated signature.
-    For example, if you have the following signature:
-
-    ```
-    class MySignature(dspy.Signature):
-        question: str = dspy.InputField()
-        history: dspy.History = dspy.InputField()
-        answer: str = dspy.OutputField()
-    ```
-
-    Then the history should be a list of dictionaries with keys "question" and "answer".
+    History supports four message formats:
+    
+    1. **Signature mode**: Dict keys match signature input/output fields → user/assistant pairs.
+       Must be explicitly set via mode="signature".
+       ```python
+       history = dspy.History(messages=[
+           {"question": "What is 2+2?", "answer": "4"},
+       ], mode="signature")
+       ```
+    
+    2. **KV mode**: Nested `{"input_fields": {...}, "output_fields": {...}}` → user/assistant pairs.
+       ```python
+       history = dspy.History.from_kv([
+           {"input_fields": {"thought": "...", "tool_name": "search"}, "output_fields": {"observation": "..."}},
+       ])
+       ```
+    
+    3. **Dict mode** (default): Arbitrary serializable key-value pairs → all in single user message.
+       ```python
+       history = dspy.History(messages=[
+           {"thought": "I need to search", "tool_name": "search", "observation": "Results found"},
+       ])
+       ```
+    
+    4. **Raw mode**: Direct LM messages with `{"role": "user", "content": "..."}` → passed through.
+       ```python
+       history = dspy.History.from_raw([
+           {"role": "user", "content": "Hello"},
+           {"role": "assistant", "content": "Hi there!"},
+       ])
+       ```
+
+    The mode is auto-detected from the first message if not explicitly provided.
 
     Example:
-        ```
+        ```python
         import dspy
 
         dspy.configure(lm=dspy.LM("openai/gpt-4o-mini"))
@@ -41,7 +63,7 @@ class MySignature(dspy.Signature):
         ```
 
     Example of capturing the conversation history:
-        ```
+        ```python
         import dspy
 
         dspy.configure(lm=dspy.LM("openai/gpt-4o-mini"))
@@ -59,10 +81,94 @@ class MySignature(dspy.Signature):
     """
 
     messages: list[dict[str, Any]]
+    mode: Literal["signature", "kv", "dict", "raw"] | None = None
 
     model_config = pydantic.ConfigDict(
         frozen=True,
         str_strip_whitespace=True,
         validate_assignment=True,
         extra="forbid",
     )
+
+    def _detect_mode(self, msg: dict) -> str:
+        """Detect the mode for a message based on its structure.
+        
+        Detection rules:
+        - Raw: has "role" and "content" keys, but NOT "input_fields"/"output_fields"
+        - KV: keys are ONLY "input_fields" and/or "output_fields"
+        - Signature: must be explicitly set (requires matching against signature fields)
+        - Dict: everything else (default) - arbitrary kv pairs go into user message
+        """
+        if self.mode:
+            return self.mode
+
+        keys = set(msg.keys())
+
+        if {"role", "content"} <= keys and not ({"input_fields", "output_fields"} & keys):
+            return "raw"
+
+        if keys <= {"input_fields", "output_fields"} and keys:
+            return "kv"
+
+        return "dict"
+
+    @pydantic.model_validator(mode="after")
+    def _validate_messages(self) -> "History":
+        for msg in self.messages:
+            detected = self._detect_mode(msg)
+
+            if detected == "raw":
+                if not isinstance(msg.get("role"), str):
+                    raise ValueError(f"'role' must be a string: {msg}")
+                # content can be None for tool call messages, or string otherwise
+                content = msg.get("content")
+                if content is not None and not isinstance(content, str):
+                    raise ValueError(f"'content' must be a string or None: {msg}")
+
+            elif detected == "kv":
+                if "input_fields" in msg and not isinstance(msg["input_fields"], dict):
+                    raise ValueError(f"'input_fields' must be a dict: {msg}")
+                if "output_fields" in msg and not isinstance(msg["output_fields"], dict):
+                    raise ValueError(f"'output_fields' must be a dict: {msg}")
+
+        return self
+
+    def with_messages(self, messages: list[dict[str, Any]]) -> "History":
+        """Return a new History with additional messages appended.
+        
+        Args:
+            messages: List of messages to append.
+            
+        Returns:
+            A new History instance with the messages appended.
+        """
+        return History(messages=[*self.messages, *messages], mode=self.mode)
+
+    @classmethod
+    def from_kv(cls, messages: list[dict[str, Any]]) -> "History":
+        """Create a History instance with KV mode.
+        
+        KV mode expects messages with "input_fields" and/or "output_fields" keys,
+        each containing a dict of field names to values.
+        
+        Args:
+            messages: List of dicts with "input_fields" and/or "output_fields" keys.
+            
+        Returns:
+            A History instance with mode="kv".
+        """
+        return cls(messages=messages, mode="kv")
+
+    @classmethod
+    def from_raw(cls, messages: list[dict[str, Any]]) -> "History":
+        """Create a History instance with raw mode.
+        
+        Raw mode expects direct LM messages with "role" and "content" keys.
+        
+        Args:
+            messages: List of dicts with "role" and "content" keys.
+            
+        Returns:
+            A History instance with mode="raw".
+        """
+        return cls(messages=messages, mode="raw")