chore: import upstream snapshot with attribution

python/semantic_kernel/contents/reasoning_content.py

@@ -0,0 +1,59 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Reasoning content model."""
+
+from html import unescape
+from typing import ClassVar, Literal, TypeVar
+from xml.etree.ElementTree import Element  # nosec
+
+from pydantic import Field
+
+from semantic_kernel.contents.const import REASONING_CONTENT_TAG, ContentTypes
+from semantic_kernel.contents.kernel_content import KernelContent
+from semantic_kernel.exceptions.content_exceptions import ContentInitializationError
+
+_T = TypeVar("_T", bound="ReasoningContent")
+
+
+class ReasoningContent(KernelContent):
+    """Represents reasoning content.
+
+    Exposes a human-readable reasoning ``text``. Any provider-specific fields (for example: ids, encrypted blobs,
+    statuses, token info) must be carried in ``metadata`` on the base ``KernelContent``.
+
+    Attributes:
+        content_type: Literal identifying this instance as reasoning content.
+        tag: XML tag name used when serializing to/from XML.
+        text: The reasoning text to surface to callers.
+
+    Methods:
+        __str__: Return the reasoning text.
+        to_element: Serialize to an XML Element using ``tag`` and ``text``.
+        from_element: Deserialize from an XML Element into a ReasoningContent.
+        to_dict: Serialize to a dict suitable for message payloads.
+    """
+
+    content_type: Literal[ContentTypes.REASONING_CONTENT] = Field(ContentTypes.REASONING_CONTENT, init=False)
+    tag: ClassVar[str] = REASONING_CONTENT_TAG
+    text: str | None = None
+
+    def __str__(self) -> str:
+        """Return the text of the reasoning content."""
+        return self.text or ""
+
+    def to_element(self) -> Element:
+        """Convert the instance to an XML Element."""
+        element = Element(self.tag)
+        element.text = self.text
+        return element
+
+    @classmethod
+    def from_element(cls: type[_T], element: Element) -> _T:
+        """Create an instance from an XML Element."""
+        if element.tag != cls.tag:
+            raise ContentInitializationError(f"Element tag is not {cls.tag}")  # pragma: no cover
+        return cls(text=unescape(element.text) if element.text else "")
+
+    def to_dict(self) -> dict[str, str]:
+        """Convert the instance to a dictionary suitable for message serialization."""
+        return {"type": "reasoning", "text": self.text or ""}