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

@@ -14,9 +14,11 @@
 
 import copy
 from collections.abc import Callable
+from functools import lru_cache
 from pathlib import Path
 from typing import Any
 
+import jinja2
 import PIL.Image
 import transformers
 from typing_extensions import override
@@ -29,6 +31,38 @@
 from oumi.utils.logging import logger
 from oumi.utils.str_utils import truncate_to_max_tokens_limit
 
+_REASONING_FIELD_NAMES = frozenset({"reasoning", "reasoning_content"})
+_jinja_env = jinja2.Environment()
+
+
+@lru_cache(maxsize=8)
+def _template_references_reasoning(template: str) -> bool:
+    """Check if a Jinja2 template references reasoning fields on messages.
+
+    Parses the template AST and walks it to find attribute access
+    (``message.reasoning_content``) or item access
+    (``message['reasoning']``) nodes that reference reasoning fields.
+    This avoids false positives from comments or unrelated text.
+    """
+    from jinja2.nodes import Const, Getattr, Getitem, Node
+
+    try:
+        ast = _jinja_env.parse(template)
+    except jinja2.TemplateSyntaxError:
+        return False
+
+    pending: list[Node] = [ast]
+    while pending:
+        node = pending.pop()
+        if isinstance(node, Getattr):
+            if node.attr in _REASONING_FIELD_NAMES:
+                return True
+        elif isinstance(node, Getitem):
+            if isinstance(node.arg, Const) and node.arg.value in _REASONING_FIELD_NAMES:
+                return True
+        pending.extend(node.iter_child_nodes())
+    return False
+
 
 class DefaultProcessor(BaseProcessor):
     """Default implementation of processor that wraps a worker processor.
@@ -226,12 +260,48 @@ def __call__(
             )
         return result
 
+    def _template_supports_reasoning(self) -> bool:
+        """Check if the chat template natively handles reasoning fields.
+
+        Parses the Jinja2 AST to find actual variable references to
+        ``reasoning`` or ``reasoning_content`` on message objects, avoiding
+        false positives from comments or unrelated text.
+        """
+        return _template_references_reasoning(self.chat_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,21 @@ 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 = None
     """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.
+
+    Named ``reasoning_content`` to match Qwen3's chat template convention.
+    The inference engines handle extracting from both ``reasoning`` and
+    ``reasoning_content`` API response fields. When passed to chat
+    templates, both key names are included in the message dict so that
+    any template can find it.
     """
 
     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

@@ -218,6 +218,7 @@ def create_list_of_message_json_dicts(
     messages: list[Message],
     *,
     group_adjacent_same_role_turns: bool,
+    include_reasoning: bool = False,
 ) -> list[dict[str, Any]]:
     """Returns a list of JSON dictionaries representing messages.
 
@@ -227,6 +228,11 @@ def create_list_of_message_json_dicts(
         messages: The input messages.
         group_adjacent_same_role_turns: Whether to pack adjacent messages
             from the same role into a single element in output list.
+        include_reasoning: Whether to include ``reasoning_content`` and
+            ``reasoning`` keys in the output dicts. Set to ``True`` when
+            building dicts for chat templates (training). Set to ``False``
+            (default) when building dicts for API requests, since some
+            providers (e.g., Anthropic) reject unknown fields.
 
     Returns:
         list[Dict[str, Any]]: The list of messages encoded as nested JSON dicts.
@@ -235,6 +241,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 +265,21 @@ def create_list_of_message_json_dicts(
                 idx += 1
             item["content"] = content_list
 
+        if include_reasoning:
+            # Collect reasoning from all messages in the group and
+            # concatenate. Include under both key names so that any chat
+            # template can find it (Qwen3 uses "reasoning_content", others
+            # may use "reasoning").
+            reasoning_parts: list[str] = [
+                rc
+                for i in range(start_idx, end_idx)
+                if (rc := messages[i].reasoning_content) is not None
+            ]
+            if reasoning_parts:
+                reasoning = "".join(reasoning_parts)
+                item["reasoning_content"] = reasoning
+                item["reasoning"] = reasoning
+
         idx = end_idx
         result.append(item)
 
@@ -308,12 +330,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 +455,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,134 @@ 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"
+
+
+def test_template_supports_reasoning_false_positive_comment():
+    """Template with 'reasoning' in a comment should NOT match."""
+    from oumi.core.processors.default_processor import _template_references_reasoning
+
+    template = """{# This template handles reasoning models #}
+{% for message in messages %}{{ message.content }}{% endfor %}"""
+    assert _template_references_reasoning(template) is False
+
+
+def test_template_supports_reasoning_false_positive_string_literal():
+    """Template with 'reasoning' in a string literal should NOT match."""
+    from oumi.core.processors.default_processor import _template_references_reasoning
+
+    template = (
+        "{% for message in messages %}"
+        '{{ "reasoning_content is not used" }}'
+        "{{ message.content }}{% endfor %}"
+    )
+    assert _template_references_reasoning(template) is False
+
+
+def test_template_supports_reasoning_attribute_access():
+    """Template with message.reasoning_content attribute access should match."""
+    from oumi.core.processors.default_processor import _template_references_reasoning
+
+    template = (
+        "{% if message.reasoning_content %}{{ message.reasoning_content }}{% endif %}"
+    )
+    assert _template_references_reasoning(template) is True
+
+
+def test_template_supports_reasoning_dict_access():
+    """Template with message['reasoning'] dict access should match."""
+    from oumi.core.processors.default_processor import _template_references_reasoning
+
+    template = """{% if message['reasoning'] %}{{ message['reasoning'] }}{% endif %}"""
+    assert _template_references_reasoning(template) is True
+
+
+def test_template_supports_reasoning_no_reasoning():
+    """Template with no reasoning references should not match."""
+    from oumi.core.processors.default_processor import _template_references_reasoning
+
+    template = """{% for m in messages %}{{ m.content }}{% endfor %}"""
+    assert _template_references_reasoning(template) is False