fix(inference): handle null content and propagate reasoning from thinking models

Some providers return content=null for thinking models when the token
budget is consumed by reasoning. This caused a Pydantic ValidationError
in Message() because content must be str | list[ContentItem], not None.

Changes:
- Add optional `reasoning_content` field to Message for per-turn
  reasoning. Named `reasoning_content` to match Qwen3's chat template
  convention — templates that support this field render it natively
  inside <think> tags
- RemoteInferenceEngine (Together, Fireworks, OpenAI, OpenRouter, Gemini,
  GCP/Vertex, Cerebras, DeepSeek, Parasail, RemoteVLLM): default content
  to empty string when null, extract reasoning from "reasoning" or
  "reasoning_content" response fields
- AnthropicInferenceEngine: extract reasoning from "thinking" content
  blocks, handle interleaved thinking/text blocks correctly
- BedrockInferenceEngine: same as Anthropic (thinking content blocks)
- SambanovaInferenceEngine: same as RemoteInferenceEngine (OpenAI-compat)
- conversation_utils: preserve reasoning_content when reconstructing
  Messages in remove_excessive_images and truncate_text_in_content_items
- SGLang/local engines: no change (reasoning embedded in text via tags)

Null handling: uses explicit `is None` checks (not truthiness) so that
empty-string reasoning is preserved correctly.

Multiple content blocks (Anthropic/Bedrock) are concatenated directly
without separators, matching Anthropic's recommended approach.

Training: models whose chat templates reference `reasoning_content`
(e.g., Qwen3) will tokenize it natively. For models without template
support, a fallback to prepend reasoning as <think> tags in content
is needed (separate follow-up).

Author: jgreer013

src/oumi/core/processors/default_processor.py

@@ -226,12 +226,44 @@ def __call__(
             )
         return result
 
+    def _template_supports_reasoning(self) -> bool:
+        """Check if the chat template natively handles reasoning fields."""
+        template = self.chat_template
+        return "reasoning_content" in template or "reasoning" in template
+
     def _convert_messages_to_dicts(self, messages: list[Message]) -> list[dict]:
-        """Converts Message objects to dict format for HuggingFace compatibility."""
-        return [
-            msg.model_dump(mode="json", exclude_none=True, exclude_unset=True)
-            for msg in messages
-        ]
+        """Converts Message objects to dict format for HuggingFace compatibility.
+
+        When a message has ``reasoning_content``, the behavior depends on
+        whether the chat template natively supports reasoning fields:
+
+        - **Template supports reasoning** (e.g., Qwen3): both
+          ``reasoning_content`` and ``reasoning`` keys are included so the
+          template can render them natively (typically inside ``<think>``
+          tags).
+        - **Template does not support reasoning** (e.g., Llama, DeepSeek):
+          reasoning is prepended to ``content`` wrapped in ``<think>`` tags
+          so it appears in the tokenized sequence.
+        """
+        template_supports = self._template_supports_reasoning()
+        result = []
+        for msg in messages:
+            d = msg.model_dump(mode="json", exclude_none=True, exclude_unset=True)
+            if msg.reasoning_content is not None:
+                if template_supports:
+                    # Pass as separate keys — template handles formatting.
+                    if "reasoning" not in d:
+                        d["reasoning"] = msg.reasoning_content
+                else:
+                    # Fold into content — template doesn't know about
+                    # reasoning, so we prepend it with <think> tags.
+                    d.pop("reasoning_content", None)
+                    content = d.get("content", "")
+                    d["content"] = (
+                        f"<think>\n{msg.reasoning_content}\n</think>\n\n{content}"
+                    )
+            result.append(d)
+        return result
 
     @override
     def apply_chat_template(

src/oumi/core/types/conversation.py

@@ -239,14 +239,23 @@ class Message(pydantic.BaseModel):
     role: Role
     """The role of the entity sending the message (e.g., user, assistant, system)."""
 
-    reasoning: str | None = None
+    reasoning_content: str | None = pydantic.Field(
+        default=None,
+        validation_alias=pydantic.AliasChoices("reasoning_content", "reasoning"),
+    )
     """Optional reasoning/thinking content from the model.
 
-    Some providers (e.g., Together) return a separate ``reasoning`` field for
-    thinking models (Qwen3.x, Qwen3.5-x). When present, ``content`` holds the
-    visible output and ``reasoning`` holds the internal chain-of-thought.
-    If the model exhausts its token budget on reasoning, ``content`` may be
-    empty while ``reasoning`` contains the partial thinking.
+    Some providers (e.g., Together) return a separate ``reasoning`` or
+    ``reasoning_content`` field for thinking models (Qwen3.x, Qwen3.5-x).
+    When present, ``content`` holds the visible output and
+    ``reasoning_content`` holds the internal chain-of-thought. If the model
+    exhausts its token budget on reasoning, ``content`` may be empty while
+    ``reasoning_content`` contains the partial thinking.
+
+    Accepts both ``reasoning_content`` and ``reasoning`` as input keys
+    (via Pydantic alias) for compatibility across providers. Always
+    serialized as ``reasoning_content`` in output to match Qwen3's chat
+    template convention.
     """
 
     def model_post_init(self, __context) -> None:

src/oumi/inference/anthropic_inference_engine.py

@@ -216,7 +216,7 @@ def _convert_api_output_to_conversation(
         new_message = Message(
             content=text,
             role=Role.ASSISTANT,
-            reasoning=reasoning,
+            reasoning_content=reasoning,
         )
         metadata = dict(original_conversation.metadata)
         usage = self._extract_usage_from_response(response)

src/oumi/inference/bedrock_inference_engine.py

@@ -371,7 +371,9 @@ def _convert_api_output_to_conversation(
                     text_parts.append(part)
         text = "".join(text_parts)
         reasoning = "".join(reasoning_parts) if reasoning_parts else None
-        new_message = Message(content=text, role=Role.ASSISTANT, reasoning=reasoning)
+        new_message = Message(
+            content=text, role=Role.ASSISTANT, reasoning_content=reasoning
+        )
         metadata = dict(original.metadata)
         finish_reason = self._extract_finish_reason_from_response(response)
         if finish_reason is not None:

src/oumi/inference/remote_inference_engine.py

@@ -504,7 +504,7 @@ def _convert_api_output_to_conversation(
                 Message(
                     content=content,
                     role=Role(message["role"]),
-                    reasoning=reasoning,
+                    reasoning_content=reasoning,
                 ),
             ],
             metadata=metadata,

src/oumi/inference/sambanova_inference_engine.py

@@ -118,7 +118,7 @@ def _convert_api_output_to_conversation(
         new_message = Message(
             content=content,
             role=Role.ASSISTANT,
-            reasoning=reasoning,
+            reasoning_content=reasoning,
         )
 
         return Conversation(

src/oumi/utils/conversation_utils.py

@@ -235,6 +235,7 @@ def create_list_of_message_json_dicts(
     result = []
     idx = 0
     while idx < num_messages:
+        start_idx = idx
         end_idx = idx + 1
         if group_adjacent_same_role_turns:
             while end_idx < num_messages and (
@@ -258,6 +259,14 @@ def create_list_of_message_json_dicts(
                 idx += 1
             item["content"] = content_list
 
+        # Include reasoning under both key names so that any chat template
+        # can find it (Qwen3 uses "reasoning_content", others may use
+        # "reasoning").  Only added when the value is not None.
+        reasoning = messages[start_idx].reasoning_content
+        if reasoning is not None:
+            item["reasoning_content"] = reasoning
+            item["reasoning"] = reasoning
+
         idx = end_idx
         result.append(item)
 
@@ -308,12 +317,20 @@ def remove_excessive_images(
         if len(filtered_items) == 1 and isinstance(filtered_items[0].content, str):
             result.append(
                 Message(
-                    id=message.id, content=filtered_items[0].content, role=message.role
+                    id=message.id,
+                    content=filtered_items[0].content,
+                    role=message.role,
+                    reasoning_content=message.reasoning_content,
                 )
             )
         else:
             result.append(
-                Message(id=message.id, content=filtered_items, role=message.role)
+                Message(
+                    id=message.id,
+                    content=filtered_items,
+                    role=message.role,
+                    reasoning_content=message.reasoning_content,
+                )
             )
 
     return result
@@ -425,11 +442,17 @@ def truncate_text_in_content_items(
             ):
                 assert isinstance(items[0].content, str)
                 result[msg_idx] = Message(
-                    id=message.id, content=items[0].content, role=message.role
+                    id=message.id,
+                    content=items[0].content,
+                    role=message.role,
+                    reasoning_content=message.reasoning_content,
                 )
             else:
                 result[msg_idx] = Message(
-                    id=message.id, content=items, role=message.role
+                    id=message.id,
+                    content=items,
+                    role=message.role,
+                    reasoning_content=message.reasoning_content,
                 )
 
     return result

tests/unit/builders/test_processors.py

@@ -338,3 +338,87 @@ def test_processor_apply_chat_template_multimodal_text_content():
     prompt = processor.apply_chat_template(messages)
     assert isinstance(prompt, str)
     assert "Describe the following:" in prompt
+
+
+def test_convert_messages_reasoning_with_supporting_template():
+    """When chat template references reasoning, pass as separate keys."""
+    from unittest.mock import MagicMock, PropertyMock
+
+    from oumi.core.processors.default_processor import DefaultProcessor
+
+    processor = MagicMock(spec=DefaultProcessor)
+    processor._convert_messages_to_dicts = (
+        DefaultProcessor._convert_messages_to_dicts.__get__(processor)
+    )
+    processor._template_supports_reasoning = (
+        DefaultProcessor._template_supports_reasoning.__get__(processor)
+    )
+    type(processor).chat_template = PropertyMock(
+        return_value="{% if message.reasoning_content %}...{% endif %}"
+    )
+
+    messages = [
+        Message(
+            role=Role.ASSISTANT,
+            content="The answer is 4.",
+            reasoning_content="2+2=4",
+        ),
+    ]
+    result = processor._convert_messages_to_dicts(messages)
+    assert result[0]["reasoning_content"] == "2+2=4"
+    assert result[0]["reasoning"] == "2+2=4"
+    assert result[0]["content"] == "The answer is 4."
+
+
+def test_convert_messages_reasoning_with_unsupporting_template():
+    """When chat template doesn't reference reasoning, fold into content."""
+    from unittest.mock import MagicMock, PropertyMock
+
+    from oumi.core.processors.default_processor import DefaultProcessor
+
+    processor = MagicMock(spec=DefaultProcessor)
+    processor._convert_messages_to_dicts = (
+        DefaultProcessor._convert_messages_to_dicts.__get__(processor)
+    )
+    processor._template_supports_reasoning = (
+        DefaultProcessor._template_supports_reasoning.__get__(processor)
+    )
+    type(processor).chat_template = PropertyMock(
+        return_value="{% for message in messages %}{{ message.content }}{% endfor %}"
+    )
+
+    messages = [
+        Message(
+            role=Role.ASSISTANT,
+            content="The answer is 4.",
+            reasoning_content="2+2=4",
+        ),
+    ]
+    result = processor._convert_messages_to_dicts(messages)
+    assert "reasoning_content" not in result[0]
+    assert "reasoning" not in result[0]
+    assert result[0]["content"] == "<think>\n2+2=4\n</think>\n\nThe answer is 4."
+
+
+def test_convert_messages_no_reasoning():
+    """When message has no reasoning, no reasoning keys in output."""
+    from unittest.mock import MagicMock, PropertyMock
+
+    from oumi.core.processors.default_processor import DefaultProcessor
+
+    processor = MagicMock(spec=DefaultProcessor)
+    processor._convert_messages_to_dicts = (
+        DefaultProcessor._convert_messages_to_dicts.__get__(processor)
+    )
+    processor._template_supports_reasoning = (
+        DefaultProcessor._template_supports_reasoning.__get__(processor)
+    )
+    type(processor).chat_template = PropertyMock(return_value="simple template")
+
+    messages = [
+        Message(role=Role.ASSISTANT, content="Hello"),
+    ]
+    result = processor._convert_messages_to_dicts(messages)
+    assert "reasoning_content" not in result[0]
+    assert "reasoning" not in result[0]
+    assert result[0]["content"] == "Hello"

tests/unit/inference/test_anthropic_inference_engine.py

@@ -114,11 +114,11 @@ def test_convert_api_output_interleaved_blocks(anthropic_engine):
         api_response, original
     )
     assert result.messages[-1].content == "First part.Second part."
-    assert result.messages[-1].reasoning == "Step 1...Step 2..."
+    assert result.messages[-1].reasoning_content == "Step 1...Step 2..."
 
 
 def test_convert_api_output_with_thinking_blocks(anthropic_engine):
-    """Test that thinking blocks are extracted into Message.reasoning."""
+    """Test that thinking blocks are extracted into Message.reasoning_content."""
     original = Conversation(
         messages=[Message(content="Hello", role=Role.USER)],
     )
@@ -136,7 +136,7 @@ def test_convert_api_output_with_thinking_blocks(anthropic_engine):
         api_response, original
     )
     assert result.messages[-1].content == "Here is my answer."
-    assert result.messages[-1].reasoning == "Let me reason about this..."
+    assert result.messages[-1].reasoning_content == "Let me reason about this..."
 
 
 def test_convert_api_output_no_thinking_blocks(anthropic_engine):
@@ -149,7 +149,7 @@ def test_convert_api_output_no_thinking_blocks(anthropic_engine):
         api_response, original
     )
     assert result.messages[-1].content == "Simple answer."
-    assert result.messages[-1].reasoning is None
+    assert result.messages[-1].reasoning_content is None
 
 
 def test_convert_api_output_null_thinking_content(anthropic_engine):
@@ -168,7 +168,7 @@ def test_convert_api_output_null_thinking_content(anthropic_engine):
         api_response, original
     )
     assert result.messages[-1].content == "Answer."
-    assert result.messages[-1].reasoning is None
+    assert result.messages[-1].reasoning_content is None
 
 
 def test_convert_api_output_null_text_content(anthropic_engine):
@@ -186,7 +186,7 @@ def test_convert_api_output_null_text_content(anthropic_engine):
         api_response, original
     )
     assert result.messages[-1].content == ""
-    assert result.messages[-1].reasoning == "Reasoning here."
+    assert result.messages[-1].reasoning_content == "Reasoning here."
 
 
 @pytest.mark.parametrize(

tests/unit/inference/test_bedrock_inference_engine.py

@@ -103,7 +103,7 @@ def test_convert_api_output_to_conversation(bedrock_engine):
 
 @pytest.mark.skipif(boto3_import_failed, reason="boto3 not available")
 def test_convert_api_output_with_thinking_blocks(bedrock_engine):
-    """Test that thinking blocks are extracted into Message.reasoning."""
+    """Test that thinking blocks are extracted into Message.reasoning_content."""
     original = Conversation(
         messages=[Message(content="Hello", role=Role.USER)],
     )
@@ -122,7 +122,7 @@ def test_convert_api_output_with_thinking_blocks(bedrock_engine):
     }
     result = bedrock_engine._convert_api_output_to_conversation(api_response, original)
     assert result.messages[-1].content == "The answer is 42."
-    assert result.messages[-1].reasoning == "Step 1: analyze..."
+    assert result.messages[-1].reasoning_content == "Step 1: analyze..."
 
 
 @pytest.mark.skipif(boto3_import_failed, reason="boto3 not available")
@@ -134,7 +134,7 @@ def test_convert_api_output_no_thinking_blocks(bedrock_engine):
     api_response = {"output": {"message": {"content": [{"text": "Simple answer."}]}}}
     result = bedrock_engine._convert_api_output_to_conversation(api_response, original)
     assert result.messages[-1].content == "Simple answer."
-    assert result.messages[-1].reasoning is None
+    assert result.messages[-1].reasoning_content is None
 
 
 @pytest.mark.skipif(boto3_import_failed, reason="boto3 not available")