From d308dd84386aa19590d1fb09c4d29c1227d6c56f Mon Sep 17 00:00:00 2001
From: Isaac Miller <isaacbmiller@gmail.com>
Date: Fri, 5 Dec 2025 10:17:34 -0500
Subject: [PATCH 1/4] Continue refactor

---
 dspy/adapters/base.py               | 128 ++++++++---
 dspy/adapters/types/history.py      | 153 +++++++++++--
 dspy/utils/inspect_history.py       | 100 +++++---
 tests/adapters/test_baml_adapter.py |  10 +-
 tests/adapters/test_chat_adapter.py | 340 +++++++++++++++++++++++++++-
 tests/adapters/test_json_adapter.py |  10 +-
 6 files changed, 643 insertions(+), 98 deletions(-)

diff --git a/dspy/adapters/base.py b/dspy/adapters/base.py
index 8696697d3a..08b0dcc06b 100644
--- a/dspy/adapters/base.py
+++ b/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
 
@@ -452,13 +453,13 @@ def format_demos(self, signature: type[Signature], demos: list[dict[str, Any]])
 
         return messages
 
-    def _get_history_field_name(self, signature: type[Signature]) -> bool:
+    def _get_history_field_name(self, signature: type[Signature]) -> str | None:
         for name, field in signature.input_fields.items():
             if field.annotation == History:
                 return name
         return None
 
-    def _get_tool_call_input_field_name(self, signature: type[Signature]) -> bool:
+    def _get_tool_call_input_field_name(self, signature: type[Signature]) -> str | None:
         for name, field in signature.input_fields.items():
             # Look for annotation `list[dspy.Tool]` or `dspy.Tool`
             origin = get_origin(field.annotation)
@@ -468,54 +469,119 @@ def _get_tool_call_input_field_name(self, signature: type[Signature]) -> bool:
                 return name
         return None
 
-    def _get_tool_call_output_field_name(self, signature: type[Signature]) -> bool:
+    def _get_tool_call_output_field_name(self, signature: type[Signature]) -> str | None:
         for name, field in signature.output_fields.items():
             if field.annotation == ToolCalls:
                 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],
         history_field_name: str,
         inputs: dict[str, Any],
     ) -> list[dict[str, Any]]:
-        """Format the conversation history.
+        """Format the conversation history as multiturn messages.
 
-        This method formats the conversation history and the current input as multiturn messages.
-
-        Args:
-            signature: The DSPy signature for which to format the conversation history.
-            history_field_name: The name of the history field in the signature.
-            inputs: The input arguments to the DSPy module.
+        Supports four modes:
+        - raw: Direct LM messages → passed through as-is
+        - demo: {"input_fields": {...}, "output_fields": {...}} → user/assistant pairs
+        - flat: Arbitrary kv pairs → single user message per dict (default)
+        - signature: Dict keys match signature fields → user/assistant pairs
 
-        Returns:
-            A list of multiturn messages.
+        For backward compatibility, flat-mode histories whose message keys are subsets of the
+        signature fields (and overlap output fields) are treated as signature-mode.
         """
-        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(
-                {
+        del inputs[history_field_name]
+
+        if history.mode == "raw":
+            return [dict(msg) for msg in history.messages]
+        if history.mode == "demo":
+            return self._format_demo_history(history.messages)
+        if history.mode == "signature":
+            return self._format_signature_history(signature, history.messages)
+
+        # Backward-compat shim: treat flat-mode as signature-mode if messages look like
+        # signature-style conversation history (keys subset of signature fields, overlapping outputs)
+        if history.mode == "flat" and history.messages:
+            sig_keys = set(signature.fields.keys())
+            output_keys = set(signature.output_fields.keys())
+            msg_key_sets = [set(m.keys()) for m in history.messages]
+
+            if all(ks <= sig_keys for ks in msg_key_sets):
+                if any(ks & output_keys for ks in msg_key_sets):
+                    return self._format_signature_history(signature, history.messages)
+
+        return self._format_flat_history(history.messages)
+
+    def _format_demo_history(self, messages: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        """Format demo-mode history (input_fields/output_fields → user/assistant)."""
+        result = []
+        for msg in messages:
+            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()))
+                result.append({
                     "role": "user",
-                    "content": self.format_user_message_content(signature, message),
-                }
-            )
-            messages.append(
-                {
+                    "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()))
+                result.append({
                     "role": "assistant",
-                    "content": self.format_assistant_message_content(signature, message),
-                }
-            )
-
-        # Remove the history field from the inputs
-        del inputs[history_field_name]
+                    "content": self.format_assistant_message_content(sig, output_dict),
+                })
+        return result
 
-        return messages
+    def _format_signature_history(
+        self, signature: type[Signature], messages: list[dict[str, Any]]
+    ) -> list[dict[str, Any]]:
+        """Format signature-mode history (signature fields → user/assistant pairs)."""
+        result = []
+        for msg in messages:
+            result.append({
+                "role": "user",
+                "content": self.format_user_message_content(signature, msg),
+            })
+            result.append({
+                "role": "assistant",
+                "content": self.format_assistant_message_content(signature, msg),
+            })
+        return result
+
+    def _format_flat_history(self, messages: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        """Format flat-mode history (all kv pairs in single user message)."""
+        result = []
+        for msg in messages:
+            serialized = {k: self._serialize_kv_value(v) for k, v in msg.items()}
+            sig = self._make_dynamic_signature_for_inputs(list(serialized.keys()))
+            result.append({
+                "role": "user",
+                "content": self.format_user_message_content(sig, serialized),
+            })
+        return result
 
     def parse(self, signature: type[Signature], completion: str) -> dict[str, Any]:
         """Parse the LM output into a dictionary of the output fields.
diff --git a/dspy/adapters/types/history.py b/dspy/adapters/types/history.py
index 2c39d5c4ab..b177396089 100644
--- a/dspy/adapters/types/history.py
+++ b/dspy/adapters/types/history.py
@@ -1,25 +1,47 @@
-from typing import Any
+import warnings
+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".
+    """Class representing conversation history.
+
+    History supports four message formats via the `mode` parameter:
+
+    1. **Raw mode**: Direct LM messages with `{"role": "...", "content": "..."}`.
+       Used for ReAct trajectories and native tool calling.
+       ```python
+       history = dspy.History(messages=[
+           {"role": "user", "content": "Hello"},
+           {"role": "assistant", "content": "Hi there!"},
+       ], mode="raw")
+       ```
+
+    2. **Demo mode**: Nested `{"input_fields": {...}, "output_fields": {...}}` pairs.
+       Used for few-shot demonstrations with explicit input/output separation.
+       ```python
+       history = dspy.History(messages=[
+           {"input_fields": {"question": "2+2?"}, "output_fields": {"answer": "4"}},
+       ], mode="demo")
+       ```
+
+    3. **Flat mode** (default): Arbitrary key-value pairs in a single user message.
+       ```python
+       history = dspy.History(messages=[
+           {"thought": "I need to search", "tool_name": "search", "observation": "Found it"},
+       ])
+       ```
+
+    4. **Signature mode**: Dict keys match signature fields → user/assistant pairs.
+       ```python
+       history = dspy.History(messages=[
+           {"question": "What is 2+2?", "answer": "4"},
+       ], mode="signature")
+       ```
 
     Example:
-        ```
+        ```python
         import dspy
 
         dspy.configure(lm=dspy.LM("openai/gpt-4o-mini"))
@@ -29,19 +51,16 @@ class MySignature(dspy.Signature):
             history: dspy.History = dspy.InputField()
             answer: str = dspy.OutputField()
 
-        history = dspy.History(
-            messages=[
-                {"question": "What is the capital of France?", "answer": "Paris"},
-                {"question": "What is the capital of Germany?", "answer": "Berlin"},
-            ]
-        )
+        history = dspy.History(messages=[
+            {"question": "What is the capital of France?", "answer": "Paris"},
+        ], mode="signature")
 
         predict = dspy.Predict(MySignature)
         outputs = predict(question="What is the capital of France?", history=history)
         ```
 
     Example of capturing the conversation history:
-        ```
+        ```python
         import dspy
 
         dspy.configure(lm=dspy.LM("openai/gpt-4o-mini"))
@@ -53,12 +72,19 @@ class MySignature(dspy.Signature):
 
         predict = dspy.Predict(MySignature)
         outputs = predict(question="What is the capital of France?")
-        history = dspy.History(messages=[{"question": "What is the capital of France?", **outputs}])
+        history = dspy.History(messages=[{"question": "What is the capital of France?", **outputs}], mode="signature")
         outputs_with_history = predict(question="Are you sure?", history=history)
         ```
     """
 
     messages: list[dict[str, Any]]
+    mode: Literal["signature", "demo", "flat", "raw"] = "flat"
+    """The message format mode for this history.
+
+    Note: For backward compatibility, some adapters (e.g., ChatAdapter) may treat
+    flat-mode histories whose keys match a signature's fields as signature-mode,
+    formatting them as user/assistant pairs rather than single user messages.
+    """
 
     model_config = pydantic.ConfigDict(
         frozen=True,
@@ -66,3 +92,84 @@ class MySignature(dspy.Signature):
         validate_assignment=True,
         extra="forbid",
     )
+
+    @staticmethod
+    def _infer_mode_from_msg(msg: dict) -> str:
+        """Infer the mode from a message's structure.
+
+        Detection rules (conservative):
+        - Raw: has "role" key and ONLY LM-like keys (role, content, tool_calls, tool_call_id, name)
+        - Demo: keys are ONLY "input_fields" and/or "output_fields"
+        - Flat: everything else (signature mode must be explicit)
+        """
+        keys = set(msg.keys())
+        lm_keys = {"role", "content", "tool_calls", "tool_call_id", "name"}
+
+        if "role" in keys and keys <= lm_keys:
+            return "raw"
+
+        if keys <= {"input_fields", "output_fields"} and keys:
+            return "demo"
+
+        return "flat"
+
+    def _validate_msg_for_mode(self, msg: dict, mode: str) -> None:
+        """Validate a message conforms to the expected mode structure."""
+        if mode == "raw":
+            if not isinstance(msg.get("role"), str):
+                raise ValueError(f"Raw mode: 'role' must be a string: {msg}")
+            content = msg.get("content")
+            if content is not None and not isinstance(content, (str, list)):
+                raise ValueError(f"Raw mode: 'content' must be a string, list, or None: {msg}")
+
+        elif mode == "demo":
+            if "input_fields" in msg and not isinstance(msg["input_fields"], dict):
+                raise ValueError(f"Demo mode: 'input_fields' must be a dict: {msg}")
+            if "output_fields" in msg and not isinstance(msg["output_fields"], dict):
+                raise ValueError(f"Demo mode: 'output_fields' must be a dict: {msg}")
+
+        elif mode == "signature":
+            if not isinstance(msg, dict) or not msg:
+                raise ValueError(f"Signature mode: messages must be non-empty dicts: {msg}")
+
+    def _warn_if_likely_wrong_mode(self, msg: dict, stacklevel: int = 2) -> None:
+        """Warn if a flat-mode message looks like it was intended for another mode."""
+        keys = set(msg.keys())
+
+        if "role" in keys:
+            warnings.warn(
+                f"History message has 'role' key but is in flat mode. "
+                f"Did you mean to use mode='raw'? Message keys: {sorted(keys)}",
+                UserWarning,
+                stacklevel=stacklevel,
+            )
+        elif keys & {"input_fields", "output_fields"}:
+            warnings.warn(
+                f"History message has 'input_fields'/'output_fields' but is in flat mode. "
+                f"Did you mean to use mode='demo'? Message keys: {sorted(keys)}",
+                UserWarning,
+                stacklevel=stacklevel,
+            )
+
+    @pydantic.model_validator(mode="after")
+    def _validate_messages(self) -> "History":
+        if not self.messages:
+            return self
+
+        # Only infer if mode is the default "flat" and messages clearly match another mode
+        if self.mode == "flat":
+            inferred = self._infer_mode_from_msg(self.messages[0])
+            if inferred in {"raw", "demo"}:
+                object.__setattr__(self, "mode", inferred)
+
+        for msg in self.messages:
+            self._validate_msg_for_mode(msg, self.mode)
+            if self.mode == "flat":
+                # stacklevel=6: warn -> _warn_if_likely_wrong_mode -> _validate_messages -> validator -> __init__ -> caller
+                self._warn_if_likely_wrong_mode(msg, stacklevel=6)
+
+        return self
+
+    def with_messages(self, messages: list[dict[str, Any]]) -> "History":
+        """Return a new History with additional messages appended."""
+        return History(messages=[*self.messages, *messages], mode=self.mode)
diff --git a/dspy/utils/inspect_history.py b/dspy/utils/inspect_history.py
index 07934157fd..65a32fab25 100644
--- a/dspy/utils/inspect_history.py
+++ b/dspy/utils/inspect_history.py
@@ -10,6 +10,14 @@ def _blue(text: str, end: str = "\n"):
     return "\x1b[34m" + str(text) + "\x1b[0m" + end
 
 
+def _yellow(text: str, end: str = "\n"):
+    return "\x1b[33m" + str(text) + "\x1b[0m" + end
+
+
+def _cyan(text: str, end: str = "\n"):
+    return "\x1b[36m" + str(text) + "\x1b[0m" + end
+
+
 def pretty_print_history(history, n: int = 1):
     """Prints the last n prompts and their completions."""
 
@@ -22,37 +30,67 @@ def pretty_print_history(history, n: int = 1):
         print("\x1b[34m" + f"[{timestamp}]" + "\x1b[0m" + "\n")
 
         for msg in messages:
-            print(_red(f"{msg['role'].capitalize()} message:"))
-            if isinstance(msg["content"], str):
-                print(msg["content"].strip())
-            else:
-                if isinstance(msg["content"], list):
-                    for c in msg["content"]:
-                        if c["type"] == "text":
-                            print(c["text"].strip())
-                        elif c["type"] == "image_url":
-                            image_str = ""
-                            if "base64" in c["image_url"].get("url", ""):
-                                len_base64 = len(c["image_url"]["url"].split("base64,")[1])
-                                image_str = (
-                                    f"<{c['image_url']['url'].split('base64,')[0]}base64,"
-                                    f"<IMAGE BASE 64 ENCODED({len_base64!s})>"
-                                )
-                            else:
-                                image_str = f"<image_url: {c['image_url']['url']}>"
-                            print(_blue(image_str.strip()))
-                        elif c["type"] == "input_audio":
-                            audio_format = c["input_audio"]["format"]
-                            len_audio = len(c["input_audio"]["data"])
-                            audio_str = f"<audio format='{audio_format}' base64-encoded, length={len_audio}>"
-                            print(_blue(audio_str.strip()))
-                        elif c["type"] == "file" or c["type"] == "input_file":
-                            file = c.get("file", c.get("input_file", {}))
-                            filename = file.get("filename", "")
-                            file_id = file.get("file_id", "")
-                            file_data = file.get("file_data", "")
-                            file_str = f"<file: name:{filename}, id:{file_id}, data_length:{len(file_data)}>"
-                            print(_blue(file_str.strip()))
+            role = msg.get("role", "unknown")
+
+            # Handle tool response messages
+            if role == "tool":
+                tool_call_id = msg.get("tool_call_id", "unknown")
+                print(_yellow(f"Tool response (id: {tool_call_id}):"))
+                content = msg.get("content", "")
+                if content:
+                    print(content.strip() if isinstance(content, str) else str(content))
+                print("\n")
+                continue
+
+            print(_red(f"{role.capitalize()} message:"))
+
+            # Handle tool_calls in assistant messages
+            if role == "assistant" and msg.get("tool_calls"):
+                content = msg.get("content")
+                if content:
+                    print(content.strip() if isinstance(content, str) else str(content))
+                print(_cyan("Tool calls:"))
+                for tool_call in msg["tool_calls"]:
+                    func = tool_call.get("function", {})
+                    tool_id = tool_call.get("id", "unknown")
+                    name = func.get("name", "unknown")
+                    args = func.get("arguments", "{}")
+                    print(_cyan(f"  [{tool_id}] {name}({args})"))
+                print("\n")
+                continue
+
+            content = msg.get("content")
+            if content is None:
+                print("<no content>")
+            elif isinstance(content, str):
+                print(content.strip())
+            elif isinstance(content, list):
+                for c in content:
+                    if c["type"] == "text":
+                        print(c["text"].strip())
+                    elif c["type"] == "image_url":
+                        image_str = ""
+                        if "base64" in c["image_url"].get("url", ""):
+                            len_base64 = len(c["image_url"]["url"].split("base64,")[1])
+                            image_str = (
+                                f"<{c['image_url']['url'].split('base64,')[0]}base64,"
+                                f"<IMAGE BASE 64 ENCODED({len_base64!s})>"
+                            )
+                        else:
+                            image_str = f"<image_url: {c['image_url']['url']}>"
+                        print(_blue(image_str.strip()))
+                    elif c["type"] == "input_audio":
+                        audio_format = c["input_audio"]["format"]
+                        len_audio = len(c["input_audio"]["data"])
+                        audio_str = f"<audio format='{audio_format}' base64-encoded, length={len_audio}>"
+                        print(_blue(audio_str.strip()))
+                    elif c["type"] == "file" or c["type"] == "input_file":
+                        file = c.get("file", c.get("input_file", {}))
+                        filename = file.get("filename", "")
+                        file_id = file.get("file_id", "")
+                        file_data = file.get("file_data", "")
+                        file_str = f"<file: name:{filename}, id:{file_id}, data_length:{len(file_data)}>"
+                        print(_blue(file_str.strip()))
             print("\n")
 
         if isinstance(outputs[0], dict):
diff --git a/tests/adapters/test_baml_adapter.py b/tests/adapters/test_baml_adapter.py
index eaaa4f0d23..96afe81421 100644
--- a/tests/adapters/test_baml_adapter.py
+++ b/tests/adapters/test_baml_adapter.py
@@ -357,12 +357,10 @@ class TestSignature(dspy.Signature):
         question: str = dspy.InputField()
         answer: str = dspy.OutputField()
 
-    history = dspy.History(
-        messages=[
-            {"question": "What is the patient's age?", "answer": "45 years old"},
-            {"question": "Any allergies?", "answer": "Penicillin allergy"},
-        ]
-    )
+    history = dspy.History(messages=[
+        {"question": "What is the patient's age?", "answer": "45 years old"},
+        {"question": "Any allergies?", "answer": "Penicillin allergy"},
+    ], mode="signature")
 
     adapter = BAMLAdapter()
     messages = adapter.format(TestSignature, [], {"history": history, "question": "What medications should we avoid?"})
diff --git a/tests/adapters/test_chat_adapter.py b/tests/adapters/test_chat_adapter.py
index adb0dfed22..2d9c37815e 100644
--- a/tests/adapters/test_chat_adapter.py
+++ b/tests/adapters/test_chat_adapter.py
@@ -408,7 +408,8 @@ class MySignature(dspy.Signature):
         messages=[
             {"question": "What is the capital of France?", "answer": "Paris"},
             {"question": "What is the capital of Germany?", "answer": "Berlin"},
-        ]
+        ],
+        mode="signature",
     )
 
     adapter = dspy.ChatAdapter()
@@ -710,3 +711,340 @@ class MySignature(dspy.Signature):
 In adhering to this structure, your objective is: 
         Answer the question with multiple answers and scores"""
     assert system_message == expected_system_message
+
+
+class TestHistoryModes:
+    """Tests for History mode detection and adapter formatting."""
+
+    def test_history_mode_detection_flat_default(self):
+        """Messages with arbitrary keys are detected as flat mode (default)."""
+        history = dspy.History(messages=[{"question": "...", "answer": "..."}])
+        assert history.mode == "flat"
+
+    def test_history_mode_detection_demo(self):
+        """Messages with only input_fields/output_fields keys are detected as demo mode."""
+        history = dspy.History(messages=[{"input_fields": {"a": 1}, "output_fields": {"b": 2}}])
+        assert history.mode == "demo"
+
+    def test_history_mode_detection_demo_input_only(self):
+        """Messages with only input_fields are detected as demo mode."""
+        history = dspy.History(messages=[{"input_fields": {"a": 1}}])
+        assert history.mode == "demo"
+
+    def test_history_mode_detection_raw(self):
+        """Messages with role+content are detected as raw mode."""
+        history = dspy.History(messages=[{"role": "user", "content": "hello"}])
+        assert history.mode == "raw"
+
+    def test_history_mode_detection_raw_with_tool_calls(self):
+        """Raw mode detected for tool_calls messages."""
+        history = dspy.History(messages=[
+            {"role": "assistant", "content": None, "tool_calls": [{"id": "1", "type": "function", "function": {"name": "test", "arguments": "{}"}}]}
+        ])
+        assert history.mode == "raw"
+
+    def test_history_mode_detection_flat_with_extra_keys(self):
+        """Messages with role+content AND extra keys fallback to flat mode."""
+        history = dspy.History(messages=[{"role": "user", "content": "hello", "extra": "data"}])
+        assert history.mode == "flat"
+
+    def test_history_mode_detection_flat_with_input_fields_and_extra(self):
+        """Messages with input_fields AND extra keys fallback to flat mode."""
+        history = dspy.History(messages=[{"question": "...", "input_fields": {"a": 1}}])
+        assert history.mode == "flat"
+
+    def test_history_explicit_mode_override(self):
+        """Explicit mode overrides auto-detection."""
+        history = dspy.History(messages=[{"question": "...", "answer": "..."}], mode="signature")
+        assert history.mode == "signature"
+
+    def test_history_validation_demo_non_dict_input_fields(self):
+        """Demo mode with non-dict input_fields raises ValueError."""
+        with pytest.raises(ValueError, match="'input_fields' must be a dict"):
+            dspy.History(messages=[{"input_fields": "not a dict"}])
+
+    def test_history_validation_raw_non_string_content(self):
+        """Raw mode with non-string content raises ValueError."""
+        with pytest.raises(ValueError, match="'content' must be a string, list, or None"):
+            dspy.History(messages=[{"role": "user", "content": 123}])
+
+    def test_history_validation_raw_allows_none_content(self):
+        """Raw mode allows None content for tool call messages."""
+        history = dspy.History(messages=[
+            {"role": "assistant", "content": None, "tool_calls": [{"id": "1", "type": "function", "function": {"name": "test", "arguments": "{}"}}]}
+        ])
+        assert history.messages[0]["content"] is None
+
+    def test_history_validation_raw_non_string_role(self):
+        """Raw mode with non-string role raises ValueError."""
+        with pytest.raises(ValueError, match="'role' must be a string"):
+            dspy.History(messages=[{"role": 123, "content": "hello"}])
+
+    def test_history_explicit_demo_mode(self):
+        """Explicit mode='demo' sets demo mode."""
+        history = dspy.History(messages=[{"input_fields": {"a": 1}}], mode="demo")
+        assert history.mode == "demo"
+
+    def test_history_explicit_raw_mode(self):
+        """Explicit mode='raw' sets raw mode."""
+        history = dspy.History(messages=[{"role": "user", "content": "hello"}], mode="raw")
+        assert history.mode == "raw"
+
+    def test_history_explicit_signature_mode(self):
+        """Explicit mode='signature' sets signature mode."""
+        history = dspy.History(messages=[{"question": "...", "answer": "..."}], mode="signature")
+        assert history.mode == "signature"
+
+    def test_adapter_formats_demo_mode_history(self):
+        """Adapter correctly formats demo-mode history."""
+        class MySignature(dspy.Signature):
+            question: str = dspy.InputField()
+            history: dspy.History = dspy.InputField()
+            answer: str = dspy.OutputField()
+
+        history = dspy.History(messages=[
+            {
+                "input_fields": {"thought": "I need to search", "tool_name": "search"},
+                "output_fields": {"observation": "Results found"},
+            }
+        ])
+
+        adapter = dspy.ChatAdapter()
+        messages = adapter.format(MySignature, [], {"question": "test", "history": history})
+
+        # Should have: system, user (thought+tool_name), assistant (observation), user (question)
+        assert len(messages) == 4
+        assert messages[1]["role"] == "user"
+        assert "thought" in messages[1]["content"]
+        assert "tool_name" in messages[1]["content"]
+        assert messages[2]["role"] == "assistant"
+        assert "observation" in messages[2]["content"]
+
+    def test_adapter_formats_raw_mode_history(self):
+        """Adapter correctly formats raw-mode history."""
+        class MySignature(dspy.Signature):
+            question: str = dspy.InputField()
+            history: dspy.History = dspy.InputField()
+            answer: str = dspy.OutputField()
+
+        history = dspy.History(messages=[
+            {"role": "user", "content": "Hello"},
+            {"role": "assistant", "content": "Hi there!"},
+        ])
+
+        adapter = dspy.ChatAdapter()
+        messages = adapter.format(MySignature, [], {"question": "test", "history": history})
+
+        # Should have: system, user (Hello), assistant (Hi there!), user (test question)
+        assert len(messages) == 4
+        assert messages[1] == {"role": "user", "content": "Hello"}
+        assert messages[2] == {"role": "assistant", "content": "Hi there!"}
+
+    def test_adapter_demo_mode_serializes_complex_values(self):
+        """Demo mode serializes non-primitive values to strings."""
+        class MySignature(dspy.Signature):
+            question: str = dspy.InputField()
+            history: dspy.History = dspy.InputField()
+            answer: str = dspy.OutputField()
+
+        history = dspy.History(messages=[
+            {
+                "input_fields": {"args": {"key": "value"}, "number": 42},
+                "output_fields": {"result": ["a", "b", "c"]},
+            }
+        ])
+
+        adapter = dspy.ChatAdapter()
+        messages = adapter.format(MySignature, [], {"question": "test", "history": history})
+
+        # Values should be serialized to strings
+        assert "args" in messages[1]["content"]
+        assert "number" in messages[1]["content"]
+        assert "result" in messages[2]["content"]
+
+    def test_adapter_demo_mode_input_only(self):
+        """Demo mode with only input_fields produces only user message."""
+        class MySignature(dspy.Signature):
+            question: str = dspy.InputField()
+            history: dspy.History = dspy.InputField()
+            answer: str = dspy.OutputField()
+
+        history = dspy.History(messages=[{"input_fields": {"thought": "Thinking..."}}])
+
+        adapter = dspy.ChatAdapter()
+        messages = adapter.format(MySignature, [], {"question": "test", "history": history})
+
+        # Should have: system, user (thought), user (question)
+        assert len(messages) == 3
+        assert messages[1]["role"] == "user"
+        assert "thought" in messages[1]["content"]
+
+    def test_adapter_formats_flat_mode_history(self):
+        """Flat mode (default) puts all kv pairs in single user message."""
+        class MySignature(dspy.Signature):
+            question: str = dspy.InputField()
+            history: dspy.History = dspy.InputField()
+            answer: str = dspy.OutputField()
+
+        history = dspy.History(messages=[
+            {"thought": "I need to search", "tool_name": "search", "observation": "Results found"},
+        ])
+
+        adapter = dspy.ChatAdapter()
+        messages = adapter.format(MySignature, [], {"question": "test", "history": history})
+
+        # Should have: system, user (all fields), user (question)
+        assert len(messages) == 3
+        assert messages[1]["role"] == "user"
+        assert "thought" in messages[1]["content"]
+        assert "tool_name" in messages[1]["content"]
+        assert "observation" in messages[1]["content"]
+
+    def test_adapter_formats_signature_mode_history(self):
+        """Signature mode produces user/assistant pairs matching signature fields."""
+        class MySignature(dspy.Signature):
+            question: str = dspy.InputField()
+            history: dspy.History = dspy.InputField()
+            answer: str = dspy.OutputField()
+
+        history = dspy.History(messages=[
+            {"question": "What is 2+2?", "answer": "4"},
+        ], mode="signature")
+
+        adapter = dspy.ChatAdapter()
+        messages = adapter.format(MySignature, [], {"question": "test", "history": history})
+
+        # Should have: system, user (question), assistant (answer), user (question)
+        assert len(messages) == 4
+        assert messages[1]["role"] == "user"
+        assert "What is 2+2?" in messages[1]["content"]
+        assert messages[2]["role"] == "assistant"
+        assert "4" in messages[2]["content"]
+
+    def test_history_with_messages_preserves_mode(self):
+        """with_messages() preserves mode and validates new messages."""
+        base = dspy.History(messages=[{"role": "user", "content": "hi"}])
+        extended = base.with_messages([{"role": "assistant", "content": "hello"}])
+        assert extended.mode == "raw"
+        assert len(extended.messages) == 2
+        assert extended.messages[1]["content"] == "hello"
+
+    def test_history_with_messages_validates_new_messages(self):
+        """with_messages() validates appended messages against the mode."""
+        base = dspy.History(messages=[{"role": "user", "content": "hi"}])
+        with pytest.raises(ValueError, match="'content' must be a string"):
+            base.with_messages([{"role": "assistant", "content": 123}])
+
+    def test_history_raw_mode_allows_multimodal_content(self):
+        """Raw mode allows list content for multimodal messages."""
+        history = dspy.History(messages=[
+            {"role": "user", "content": [{"type": "text", "text": "Hello"}, {"type": "image_url", "image_url": {"url": "..."}}]},
+        ])
+        assert history.mode == "raw"
+        assert isinstance(history.messages[0]["content"], list)
+
+    def test_adapter_backward_compat_flat_treated_as_signature(self):
+        """Flat-mode history with signature-like keys is treated as signature-mode for backward compat."""
+        class MySignature(dspy.Signature):
+            question: str = dspy.InputField()
+            history: dspy.History = dspy.InputField()
+            answer: str = dspy.OutputField()
+
+        # Old-style: no explicit mode, but keys match signature
+        history = dspy.History(messages=[
+            {"question": "What is 2+2?", "answer": "4"},
+        ])
+        assert history.mode == "flat"  # Mode is flat
+
+        adapter = dspy.ChatAdapter()
+        messages = adapter.format(MySignature, [], {"question": "test", "history": history})
+
+        # But adapter formats as signature-mode (user/assistant pairs) for backward compat
+        assert len(messages) == 4
+        assert messages[1]["role"] == "user"
+        assert messages[2]["role"] == "assistant"
+
+    def test_adapter_flat_mode_stays_flat_with_non_signature_keys(self):
+        """Flat-mode with keys NOT matching signature stays truly flat (single user messages)."""
+        class MySignature(dspy.Signature):
+            question: str = dspy.InputField()
+            history: dspy.History = dspy.InputField()
+            answer: str = dspy.OutputField()
+
+        # Keys don't match signature fields - should stay flat
+        history = dspy.History(messages=[
+            {"thought": "I need to search", "tool_name": "search", "observation": "Found it"},
+        ])
+        assert history.mode == "flat"
+
+        adapter = dspy.ChatAdapter()
+        messages = adapter.format(MySignature, [], {"question": "test", "history": history})
+
+        # Should stay flat: system, user (all fields in one), user (question)
+        assert len(messages) == 3
+        assert messages[1]["role"] == "user"
+        assert "thought" in messages[1]["content"]
+        assert "tool_name" in messages[1]["content"]
+        assert "observation" in messages[1]["content"]
+
+    def test_adapter_flat_mode_without_output_fields_stays_flat(self):
+        """Flat-mode history with only input-like keys (no output fields) stays flat."""
+        class MySignature(dspy.Signature):
+            question: str = dspy.InputField()
+            history: dspy.History = dspy.InputField()
+            answer: str = dspy.OutputField()
+
+        # Only has "question" (input field), no "answer" (output field) - should stay flat
+        history = dspy.History(messages=[{"question": "What is 2+2?"}])
+        assert history.mode == "flat"
+
+        adapter = dspy.ChatAdapter()
+        messages = adapter.format(MySignature, [], {"question": "test", "history": history})
+
+        # Should stay flat (no output field overlap): system, user (question), user (current)
+        assert len(messages) == 3
+        assert messages[1]["role"] == "user"
+        assert messages[2]["role"] == "user"
+
+    def test_serialize_kv_value_with_unserializable_object(self):
+        """_serialize_kv_value handles objects that fail str() gracefully."""
+        class Unserializable:
+            def __str__(self):
+                raise RuntimeError("Cannot serialize")
+
+        class MySignature(dspy.Signature):
+            question: str = dspy.InputField()
+            history: dspy.History = dspy.InputField()
+            answer: str = dspy.OutputField()
+
+        history = dspy.History(messages=[
+            {"data": Unserializable(), "normal": "value"},
+        ])
+
+        adapter = dspy.ChatAdapter()
+        messages = adapter.format(MySignature, [], {"question": "test", "history": history})
+
+        # Should not crash, and should contain the fallback placeholder
+        assert len(messages) == 3
+        assert "<unserializable Unserializable>" in messages[1]["content"]
+        assert "normal" in messages[1]["content"]
+
+    def test_serialize_kv_value_with_complex_objects(self):
+        """_serialize_kv_value serializes complex objects to their string representation."""
+        class MySignature(dspy.Signature):
+            question: str = dspy.InputField()
+            history: dspy.History = dspy.InputField()
+            answer: str = dspy.OutputField()
+
+        history = dspy.History(messages=[
+            {"nested_dict": {"key": "value"}, "a_list": [1, 2, 3], "number": 42},
+        ])
+
+        adapter = dspy.ChatAdapter()
+        messages = adapter.format(MySignature, [], {"question": "test", "history": history})
+
+        # Complex objects should be stringified
+        assert "nested_dict" in messages[1]["content"]
+        assert "a_list" in messages[1]["content"]
+        # Primitives pass through
+        assert "42" in messages[1]["content"]
diff --git a/tests/adapters/test_json_adapter.py b/tests/adapters/test_json_adapter.py
index 373c01c67e..97e85de0e7 100644
--- a/tests/adapters/test_json_adapter.py
+++ b/tests/adapters/test_json_adapter.py
@@ -518,12 +518,10 @@ class MySignature(dspy.Signature):
         history: dspy.History = dspy.InputField()
         answer: str = dspy.OutputField()
 
-    history = dspy.History(
-        messages=[
-            {"question": "What is the capital of France?", "answer": "Paris"},
-            {"question": "What is the capital of Germany?", "answer": "Berlin"},
-        ]
-    )
+    history = dspy.History(messages=[
+        {"question": "What is the capital of France?", "answer": "Paris"},
+        {"question": "What is the capital of Germany?", "answer": "Berlin"},
+    ], mode="signature")
 
     adapter = dspy.JSONAdapter()
     messages = adapter.format(MySignature, [], {"question": "What is the capital of France?", "history": history})

From a1b56324403d32707d9fb8996881b95f99acfd3c Mon Sep 17 00:00:00 2001
From: Isaac Miller <isaacbmiller@gmail.com>
Date: Fri, 5 Dec 2025 10:26:48 -0500
Subject: [PATCH 2/4] fix serialization

---
 dspy/adapters/base.py | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/dspy/adapters/base.py b/dspy/adapters/base.py
index 08b0dcc06b..9a387c6ff6 100644
--- a/dspy/adapters/base.py
+++ b/dspy/adapters/base.py
@@ -8,6 +8,7 @@
 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.adapters.utils import serialize_for_json
 from dspy.experimental import Citations
 from dspy.signatures.field import InputField, OutputField
 from dspy.signatures.signature import Signature
@@ -479,10 +480,7 @@ 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__}>"
+        return serialize_for_json(v)
 
     def _make_dynamic_signature_for_inputs(self, keys: list[str]) -> type[Signature]:
         """Create a dynamic signature with input fields only (no instructions)."""

From 9f37fc2606ab9c26e3dbcbe6038826b48e39bccb Mon Sep 17 00:00:00 2001
From: Isaac Miller <isaacbmiller@gmail.com>
Date: Fri, 5 Dec 2025 11:00:55 -0500
Subject: [PATCH 3/4] Add factory methods back

---
 dspy/adapters/types/history.py | 177 ++++++++++++++++++++++-----------
 1 file changed, 120 insertions(+), 57 deletions(-)

diff --git a/dspy/adapters/types/history.py b/dspy/adapters/types/history.py
index b177396089..012e53a8d1 100644
--- a/dspy/adapters/types/history.py
+++ b/dspy/adapters/types/history.py
@@ -5,85 +5,82 @@
 
 
 class History(pydantic.BaseModel):
-    """Class representing conversation history.
-
-    History supports four message formats via the `mode` parameter:
-
-    1. **Raw mode**: Direct LM messages with `{"role": "...", "content": "..."}`.
-       Used for ReAct trajectories and native tool calling.
-       ```python
-       history = dspy.History(messages=[
-           {"role": "user", "content": "Hello"},
-           {"role": "assistant", "content": "Hi there!"},
-       ], mode="raw")
-       ```
-
-    2. **Demo mode**: Nested `{"input_fields": {...}, "output_fields": {...}}` pairs.
-       Used for few-shot demonstrations with explicit input/output separation.
-       ```python
-       history = dspy.History(messages=[
-           {"input_fields": {"question": "2+2?"}, "output_fields": {"answer": "4"}},
-       ], mode="demo")
-       ```
-
-    3. **Flat mode** (default): Arbitrary key-value pairs in a single user message.
-       ```python
-       history = dspy.History(messages=[
-           {"thought": "I need to search", "tool_name": "search", "observation": "Found it"},
-       ])
-       ```
-
-    4. **Signature mode**: Dict keys match signature fields → user/assistant pairs.
-       ```python
-       history = dspy.History(messages=[
-           {"question": "What is 2+2?", "answer": "4"},
-       ], mode="signature")
-       ```
+    """Class representing conversation history for DSPy modules.
 
-    Example:
-        ```python
-        import dspy
+    History allows you to pass previous conversation turns or context to a module.
+    Use factory methods to create History objects - DSPy will handle formatting automatically.
 
-        dspy.configure(lm=dspy.LM("openai/gpt-4o-mini"))
+    **Chat-style history** (LM messages):
+        ```python
+        history = dspy.History.from_raw([
+            {"role": "user", "content": "Hello"},
+            {"role": "assistant", "content": "Hi there!"},
+        ])
+        ```
 
-        class MySignature(dspy.Signature):
-            question: str = dspy.InputField()
-            history: dspy.History = dspy.InputField()
-            answer: str = dspy.OutputField()
+    **Signature-matched history** (previous input/output pairs):
+        ```python
+        history = dspy.History.from_signature_pairs([
+            {"question": "What is 2+2?", "answer": "4"},
+        ])
+        ```
 
-        history = dspy.History(messages=[
-            {"question": "What is the capital of France?", "answer": "Paris"},
-        ], mode="signature")
+    **Few-shot demonstrations**:
+        ```python
+        history = dspy.History.from_demos([
+            {"input_fields": {"question": "2+2?"}, "output_fields": {"answer": "4"}},
+        ])
+        ```
 
-        predict = dspy.Predict(MySignature)
-        outputs = predict(question="What is the capital of France?", history=history)
+    **Arbitrary context** (key-value pairs as user messages):
+        ```python
+        history = dspy.History.from_kv([
+            {"thought": "I need to search", "tool": "search", "result": "Found it"},
+        ])
         ```
 
-    Example of capturing the conversation history:
+    You can also pass `History(messages=[...])` directly - DSPy will infer the format
+    from the message structure when possible.
+
+    Example:
         ```python
         import dspy
 
         dspy.configure(lm=dspy.LM("openai/gpt-4o-mini"))
 
-        class MySignature(dspy.Signature):
+        class QA(dspy.Signature):
             question: str = dspy.InputField()
             history: dspy.History = dspy.InputField()
             answer: str = dspy.OutputField()
 
-        predict = dspy.Predict(MySignature)
-        outputs = predict(question="What is the capital of France?")
-        history = dspy.History(messages=[{"question": "What is the capital of France?", **outputs}], mode="signature")
-        outputs_with_history = predict(question="Are you sure?", history=history)
+        predict = dspy.Predict(QA)
+
+        # First turn
+        result = predict(question="What is the capital of France?")
+
+        # Build history from previous turn
+        history = dspy.History.from_signature_pairs([
+            {"question": "What is the capital of France?", **result}
+        ])
+
+        # Follow-up with context
+        result = predict(question="What about Germany?", history=history)
         ```
     """
 
     messages: list[dict[str, Any]]
     mode: Literal["signature", "demo", "flat", "raw"] = "flat"
-    """The message format mode for this history.
+    """Advanced: Override the message format mode.
 
-    Note: For backward compatibility, some adapters (e.g., ChatAdapter) may treat
-    flat-mode histories whose keys match a signature's fields as signature-mode,
-    formatting them as user/assistant pairs rather than single user messages.
+    In most cases, use factory methods (from_raw, from_demos, from_signature_pairs,
+    from_kv) instead of setting this directly. DSPy can also infer the mode from
+    message structure for raw and demo formats.
+
+    Modes:
+    - "raw": LM-style messages with role/content
+    - "demo": Few-shot examples with input_fields/output_fields
+    - "signature": Dict keys match signature fields → user/assistant pairs
+    - "flat": Arbitrary key-value pairs → single user messages (default)
     """
 
     model_config = pydantic.ConfigDict(
@@ -173,3 +170,69 @@ def _validate_messages(self) -> "History":
     def with_messages(self, messages: list[dict[str, Any]]) -> "History":
         """Return a new History with additional messages appended."""
         return History(messages=[*self.messages, *messages], mode=self.mode)
+
+    @classmethod
+    def from_raw(cls, messages: list[dict[str, Any]]) -> "History":
+        """Create History from LM-style messages with role/content.
+
+        Use this for chat-style conversation history or ReAct trajectories
+        that are already formatted as LM messages.
+
+        Example:
+            ```python
+            history = dspy.History.from_raw([
+                {"role": "user", "content": "Hello"},
+                {"role": "assistant", "content": "Hi there!"},
+            ])
+            ```
+        """
+        return cls(messages=messages, mode="raw")
+
+    @classmethod
+    def from_demos(cls, examples: list[dict[str, Any]]) -> "History":
+        """Create History from few-shot demonstration examples.
+
+        Each example should have 'input_fields' and/or 'output_fields' keys
+        containing the respective field dictionaries.
+
+        Example:
+            ```python
+            history = dspy.History.from_demos([
+                {"input_fields": {"question": "2+2?"}, "output_fields": {"answer": "4"}},
+            ])
+            ```
+        """
+        return cls(messages=examples, mode="demo")
+
+    @classmethod
+    def from_signature_pairs(cls, messages: list[dict[str, Any]]) -> "History":
+        """Create History from signature-matched field pairs.
+
+        Each message dict should have keys matching the signature's input/output
+        fields. Each dict becomes a user/assistant message pair.
+
+        Example:
+            ```python
+            history = dspy.History.from_signature_pairs([
+                {"question": "What is 2+2?", "answer": "4"},
+            ])
+            ```
+        """
+        return cls(messages=messages, mode="signature")
+
+    @classmethod
+    def from_kv(cls, messages: list[dict[str, Any]]) -> "History":
+        """Create History from arbitrary key-value context.
+
+        Each dict becomes a single user message containing all key-value pairs.
+        Use this when you want to pass context that should NOT be split into
+        user/assistant turns.
+
+        Example:
+            ```python
+            history = dspy.History.from_kv([
+                {"thought": "I need to search", "tool": "search", "result": "Found it"},
+            ])
+            ```
+        """
+        return cls(messages=messages, mode="flat")

From c092ae6e771b92d1084d59d9dd8205df3aefe6e8 Mon Sep 17 00:00:00 2001
From: Isaac Miller <isaacbmiller@gmail.com>
Date: Fri, 5 Dec 2025 11:45:34 -0500
Subject: [PATCH 4/4] move tests to test_history

---
 dspy/adapters/base.py               |  15 ++-
 tests/adapters/test_chat_adapter.py | 128 +--------------------
 tests/adapters/test_history.py      | 170 ++++++++++++++++++++++++++++
 3 files changed, 182 insertions(+), 131 deletions(-)
 create mode 100644 tests/adapters/test_history.py

diff --git a/dspy/adapters/base.py b/dspy/adapters/base.py
index 9a387c6ff6..84abe2867b 100644
--- a/dspy/adapters/base.py
+++ b/dspy/adapters/base.py
@@ -1,3 +1,4 @@
+import json
 import logging
 from typing import TYPE_CHECKING, Any, get_origin
 
@@ -476,11 +477,15 @@ def _get_tool_call_output_field_name(self, signature: type[Signature]) -> str |
                 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
-        return serialize_for_json(v)
+    def _serialize_kv_value(self, v: Any) -> str:
+        """Serialize a value to string for flat-mode history formatting.
+
+        Uses the same pattern as format_field_value in adapters/utils.py.
+        """
+        jsonable = serialize_for_json(v)
+        if isinstance(jsonable, (dict, list)):
+            return json.dumps(jsonable, ensure_ascii=False)
+        return str(jsonable)
 
     def _make_dynamic_signature_for_inputs(self, keys: list[str]) -> type[Signature]:
         """Create a dynamic signature with input fields only (no instructions)."""
diff --git a/tests/adapters/test_chat_adapter.py b/tests/adapters/test_chat_adapter.py
index 2d9c37815e..8a79bd9acd 100644
--- a/tests/adapters/test_chat_adapter.py
+++ b/tests/adapters/test_chat_adapter.py
@@ -713,87 +713,8 @@ class MySignature(dspy.Signature):
     assert system_message == expected_system_message
 
 
-class TestHistoryModes:
-    """Tests for History mode detection and adapter formatting."""
-
-    def test_history_mode_detection_flat_default(self):
-        """Messages with arbitrary keys are detected as flat mode (default)."""
-        history = dspy.History(messages=[{"question": "...", "answer": "..."}])
-        assert history.mode == "flat"
-
-    def test_history_mode_detection_demo(self):
-        """Messages with only input_fields/output_fields keys are detected as demo mode."""
-        history = dspy.History(messages=[{"input_fields": {"a": 1}, "output_fields": {"b": 2}}])
-        assert history.mode == "demo"
-
-    def test_history_mode_detection_demo_input_only(self):
-        """Messages with only input_fields are detected as demo mode."""
-        history = dspy.History(messages=[{"input_fields": {"a": 1}}])
-        assert history.mode == "demo"
-
-    def test_history_mode_detection_raw(self):
-        """Messages with role+content are detected as raw mode."""
-        history = dspy.History(messages=[{"role": "user", "content": "hello"}])
-        assert history.mode == "raw"
-
-    def test_history_mode_detection_raw_with_tool_calls(self):
-        """Raw mode detected for tool_calls messages."""
-        history = dspy.History(messages=[
-            {"role": "assistant", "content": None, "tool_calls": [{"id": "1", "type": "function", "function": {"name": "test", "arguments": "{}"}}]}
-        ])
-        assert history.mode == "raw"
-
-    def test_history_mode_detection_flat_with_extra_keys(self):
-        """Messages with role+content AND extra keys fallback to flat mode."""
-        history = dspy.History(messages=[{"role": "user", "content": "hello", "extra": "data"}])
-        assert history.mode == "flat"
-
-    def test_history_mode_detection_flat_with_input_fields_and_extra(self):
-        """Messages with input_fields AND extra keys fallback to flat mode."""
-        history = dspy.History(messages=[{"question": "...", "input_fields": {"a": 1}}])
-        assert history.mode == "flat"
-
-    def test_history_explicit_mode_override(self):
-        """Explicit mode overrides auto-detection."""
-        history = dspy.History(messages=[{"question": "...", "answer": "..."}], mode="signature")
-        assert history.mode == "signature"
-
-    def test_history_validation_demo_non_dict_input_fields(self):
-        """Demo mode with non-dict input_fields raises ValueError."""
-        with pytest.raises(ValueError, match="'input_fields' must be a dict"):
-            dspy.History(messages=[{"input_fields": "not a dict"}])
-
-    def test_history_validation_raw_non_string_content(self):
-        """Raw mode with non-string content raises ValueError."""
-        with pytest.raises(ValueError, match="'content' must be a string, list, or None"):
-            dspy.History(messages=[{"role": "user", "content": 123}])
-
-    def test_history_validation_raw_allows_none_content(self):
-        """Raw mode allows None content for tool call messages."""
-        history = dspy.History(messages=[
-            {"role": "assistant", "content": None, "tool_calls": [{"id": "1", "type": "function", "function": {"name": "test", "arguments": "{}"}}]}
-        ])
-        assert history.messages[0]["content"] is None
-
-    def test_history_validation_raw_non_string_role(self):
-        """Raw mode with non-string role raises ValueError."""
-        with pytest.raises(ValueError, match="'role' must be a string"):
-            dspy.History(messages=[{"role": 123, "content": "hello"}])
-
-    def test_history_explicit_demo_mode(self):
-        """Explicit mode='demo' sets demo mode."""
-        history = dspy.History(messages=[{"input_fields": {"a": 1}}], mode="demo")
-        assert history.mode == "demo"
-
-    def test_history_explicit_raw_mode(self):
-        """Explicit mode='raw' sets raw mode."""
-        history = dspy.History(messages=[{"role": "user", "content": "hello"}], mode="raw")
-        assert history.mode == "raw"
-
-    def test_history_explicit_signature_mode(self):
-        """Explicit mode='signature' sets signature mode."""
-        history = dspy.History(messages=[{"question": "...", "answer": "..."}], mode="signature")
-        assert history.mode == "signature"
+class TestHistoryAdapterFormatting:
+    """Tests for ChatAdapter formatting of History objects."""
 
     def test_adapter_formats_demo_mode_history(self):
         """Adapter correctly formats demo-mode history."""
@@ -921,28 +842,6 @@ class MySignature(dspy.Signature):
         assert messages[2]["role"] == "assistant"
         assert "4" in messages[2]["content"]
 
-    def test_history_with_messages_preserves_mode(self):
-        """with_messages() preserves mode and validates new messages."""
-        base = dspy.History(messages=[{"role": "user", "content": "hi"}])
-        extended = base.with_messages([{"role": "assistant", "content": "hello"}])
-        assert extended.mode == "raw"
-        assert len(extended.messages) == 2
-        assert extended.messages[1]["content"] == "hello"
-
-    def test_history_with_messages_validates_new_messages(self):
-        """with_messages() validates appended messages against the mode."""
-        base = dspy.History(messages=[{"role": "user", "content": "hi"}])
-        with pytest.raises(ValueError, match="'content' must be a string"):
-            base.with_messages([{"role": "assistant", "content": 123}])
-
-    def test_history_raw_mode_allows_multimodal_content(self):
-        """Raw mode allows list content for multimodal messages."""
-        history = dspy.History(messages=[
-            {"role": "user", "content": [{"type": "text", "text": "Hello"}, {"type": "image_url", "image_url": {"url": "..."}}]},
-        ])
-        assert history.mode == "raw"
-        assert isinstance(history.messages[0]["content"], list)
-
     def test_adapter_backward_compat_flat_treated_as_signature(self):
         """Flat-mode history with signature-like keys is treated as signature-mode for backward compat."""
         class MySignature(dspy.Signature):
@@ -1006,29 +905,6 @@ class MySignature(dspy.Signature):
         assert messages[1]["role"] == "user"
         assert messages[2]["role"] == "user"
 
-    def test_serialize_kv_value_with_unserializable_object(self):
-        """_serialize_kv_value handles objects that fail str() gracefully."""
-        class Unserializable:
-            def __str__(self):
-                raise RuntimeError("Cannot serialize")
-
-        class MySignature(dspy.Signature):
-            question: str = dspy.InputField()
-            history: dspy.History = dspy.InputField()
-            answer: str = dspy.OutputField()
-
-        history = dspy.History(messages=[
-            {"data": Unserializable(), "normal": "value"},
-        ])
-
-        adapter = dspy.ChatAdapter()
-        messages = adapter.format(MySignature, [], {"question": "test", "history": history})
-
-        # Should not crash, and should contain the fallback placeholder
-        assert len(messages) == 3
-        assert "<unserializable Unserializable>" in messages[1]["content"]
-        assert "normal" in messages[1]["content"]
-
     def test_serialize_kv_value_with_complex_objects(self):
         """_serialize_kv_value serializes complex objects to their string representation."""
         class MySignature(dspy.Signature):
diff --git a/tests/adapters/test_history.py b/tests/adapters/test_history.py
new file mode 100644
index 0000000000..8c48a55368
--- /dev/null
+++ b/tests/adapters/test_history.py
@@ -0,0 +1,170 @@
+import pytest
+
+import dspy
+
+
+class TestHistoryModeDetection:
+    """Tests for History mode auto-detection from message structure."""
+
+    def test_flat_is_default_mode(self):
+        """Messages with arbitrary keys default to flat mode."""
+        history = dspy.History(messages=[{"question": "...", "answer": "..."}])
+        assert history.mode == "flat"
+
+    def test_detects_demo_mode(self):
+        """Messages with only input_fields/output_fields are detected as demo mode."""
+        history = dspy.History(messages=[{"input_fields": {"a": 1}, "output_fields": {"b": 2}}])
+        assert history.mode == "demo"
+
+    def test_detects_demo_mode_input_only(self):
+        """Messages with only input_fields are detected as demo mode."""
+        history = dspy.History(messages=[{"input_fields": {"a": 1}}])
+        assert history.mode == "demo"
+
+    def test_detects_raw_mode(self):
+        """Messages with role+content are detected as raw mode."""
+        history = dspy.History(messages=[{"role": "user", "content": "hello"}])
+        assert history.mode == "raw"
+
+    def test_detects_raw_mode_with_tool_calls(self):
+        """Raw mode detected for tool_calls messages."""
+        history = dspy.History(messages=[
+            {"role": "assistant", "content": None, "tool_calls": [{"id": "1", "type": "function", "function": {"name": "test", "arguments": "{}"}}]}
+        ])
+        assert history.mode == "raw"
+
+    def test_flat_with_extra_keys_beyond_role_content(self):
+        """Messages with role+content AND extra keys fallback to flat mode."""
+        history = dspy.History(messages=[{"role": "user", "content": "hello", "extra": "data"}])
+        assert history.mode == "flat"
+
+    def test_flat_with_input_fields_and_extra_keys(self):
+        """Messages with input_fields AND extra keys fallback to flat mode."""
+        history = dspy.History(messages=[{"question": "...", "input_fields": {"a": 1}}])
+        assert history.mode == "flat"
+
+
+class TestHistoryExplicitMode:
+    """Tests for explicitly setting History mode."""
+
+    def test_explicit_mode_overrides_auto_detection(self):
+        """Explicit mode overrides auto-detection."""
+        history = dspy.History(messages=[{"question": "...", "answer": "..."}], mode="signature")
+        assert history.mode == "signature"
+
+    def test_explicit_demo_mode(self):
+        """Explicit mode='demo' sets demo mode."""
+        history = dspy.History(messages=[{"input_fields": {"a": 1}}], mode="demo")
+        assert history.mode == "demo"
+
+    def test_explicit_raw_mode(self):
+        """Explicit mode='raw' sets raw mode."""
+        history = dspy.History(messages=[{"role": "user", "content": "hello"}], mode="raw")
+        assert history.mode == "raw"
+
+    def test_explicit_signature_mode(self):
+        """Explicit mode='signature' sets signature mode."""
+        history = dspy.History(messages=[{"question": "...", "answer": "..."}], mode="signature")
+        assert history.mode == "signature"
+
+
+class TestHistoryValidation:
+    """Tests for History message validation."""
+
+    def test_demo_mode_requires_dict_input_fields(self):
+        """Demo mode with non-dict input_fields raises ValueError."""
+        with pytest.raises(ValueError, match="'input_fields' must be a dict"):
+            dspy.History(messages=[{"input_fields": "not a dict"}])
+
+    def test_raw_mode_requires_string_or_list_or_none_content(self):
+        """Raw mode with invalid content type raises ValueError."""
+        with pytest.raises(ValueError, match="'content' must be a string, list, or None"):
+            dspy.History(messages=[{"role": "user", "content": 123}])
+
+    def test_raw_mode_allows_none_content(self):
+        """Raw mode allows None content for tool call messages."""
+        history = dspy.History(messages=[
+            {"role": "assistant", "content": None, "tool_calls": [{"id": "1", "type": "function", "function": {"name": "test", "arguments": "{}"}}]}
+        ])
+        assert history.messages[0]["content"] is None
+
+    def test_raw_mode_requires_string_role(self):
+        """Raw mode with non-string role raises ValueError."""
+        with pytest.raises(ValueError, match="'role' must be a string"):
+            dspy.History(messages=[{"role": 123, "content": "hello"}])
+
+    def test_raw_mode_allows_multimodal_content(self):
+        """Raw mode allows list content for multimodal messages."""
+        history = dspy.History(messages=[
+            {"role": "user", "content": [{"type": "text", "text": "Hello"}, {"type": "image_url", "image_url": {"url": "..."}}]},
+        ])
+        assert history.mode == "raw"
+        assert isinstance(history.messages[0]["content"], list)
+
+
+class TestHistoryWithMessages:
+    """Tests for History.with_messages() method."""
+
+    def test_with_messages_preserves_mode(self):
+        """with_messages() preserves mode and validates new messages."""
+        base = dspy.History(messages=[{"role": "user", "content": "hi"}])
+        extended = base.with_messages([{"role": "assistant", "content": "hello"}])
+        assert extended.mode == "raw"
+        assert len(extended.messages) == 2
+        assert extended.messages[1]["content"] == "hello"
+
+    def test_with_messages_validates_new_messages(self):
+        """with_messages() validates appended messages against the mode."""
+        base = dspy.History(messages=[{"role": "user", "content": "hi"}])
+        with pytest.raises(ValueError, match="'content' must be a string"):
+            base.with_messages([{"role": "assistant", "content": 123}])
+
+
+class TestHistoryFactoryMethods:
+    """Tests for History factory methods."""
+
+    def test_from_raw_creates_raw_mode(self):
+        """from_raw() creates History with raw mode."""
+        history = dspy.History.from_raw([
+            {"role": "user", "content": "Hello"},
+            {"role": "assistant", "content": "Hi!"},
+        ])
+        assert history.mode == "raw"
+        assert len(history.messages) == 2
+
+    def test_from_demos_creates_demo_mode(self):
+        """from_demos() creates History with demo mode."""
+        history = dspy.History.from_demos([
+            {"input_fields": {"question": "2+2?"}, "output_fields": {"answer": "4"}},
+        ])
+        assert history.mode == "demo"
+        assert len(history.messages) == 1
+
+    def test_from_signature_pairs_creates_signature_mode(self):
+        """from_signature_pairs() creates History with signature mode."""
+        history = dspy.History.from_signature_pairs([
+            {"question": "What is 2+2?", "answer": "4"},
+        ])
+        assert history.mode == "signature"
+        assert len(history.messages) == 1
+
+    def test_from_kv_creates_flat_mode(self):
+        """from_kv() creates History with flat mode."""
+        history = dspy.History.from_kv([
+            {"thought": "I need to search", "tool": "search", "result": "Found it"},
+        ])
+        assert history.mode == "flat"
+        assert len(history.messages) == 1
+
+
+class TestHistorySerialization:
+    """Tests for History serialization."""
+
+    def test_model_dump_includes_all_fields(self):
+        """model_dump() returns dict with messages and mode."""
+        history = dspy.History(messages=[{"a": 1}], mode="flat")
+        dumped = history.model_dump()
+        assert "messages" in dumped
+        assert "mode" in dumped
+        assert dumped["messages"] == [{"a": 1}]
+        assert dumped["mode"] == "flat"