letta-nightly 0.6.39.dev20250314104053__py3-none-any.whl → 0.6.40.dev20250314173529__py3-none-any.whl

letta/schemas/letta_message.py

@@ -4,109 +4,132 @@ from typing import Annotated, List, Literal, Optional, Union
 
 from pydantic import BaseModel, Field, field_serializer, field_validator
 
-from letta.schemas.enums import MessageContentType
+from letta.schemas.letta_message_content import (
+    LettaAssistantMessageContentUnion,
+    LettaUserMessageContentUnion,
+    get_letta_assistant_message_content_union_str_json_schema,
+    get_letta_user_message_content_union_str_json_schema,
+)
 
-# Letta API style responses (intended to be easier to use vs getting true Message types)
+# ---------------------------
+# Letta API Messaging Schemas
+# ---------------------------
 
 
 class LettaMessage(BaseModel):
     """
-    Base class for simplified Letta message response type. This is intended to be used for developers who want the internal monologue, tool calls, and tool returns in a simplified format that does not include additional information other than the content and timestamp.
+    Base class for simplified Letta message response type. This is intended to be used for developers
+    who want the internal monologue, tool calls, and tool returns in a simplified format that does not
+    include additional information other than the content and timestamp.
 
-    Attributes:
+    Args:
         id (str): The ID of the message
         date (datetime): The date the message was created in ISO format
-
+        name (Optional[str]): The name of the sender of the message
     """
 
-    # NOTE: use Pydantic's discriminated unions feature: https://docs.pydantic.dev/latest/concepts/unions/#discriminated-unions
-    # see `message_type` attribute
-
     id: str
     date: datetime
+    name: Optional[str] = None
 
     @field_serializer("date")
     def serialize_datetime(self, dt: datetime, _info):
+        """
+        Remove microseconds since it seems like we're inconsistent with getting them
+        TODO: figure out why we don't always get microseconds (get_utc_time() does)
+        """
         if dt.tzinfo is None or dt.tzinfo.utcoffset(dt) is None:
             dt = dt.replace(tzinfo=timezone.utc)
-        # Remove microseconds since it seems like we're inconsistent with getting them
-        # TODO figure out why we don't always get microseconds (get_utc_time() does)
         return dt.isoformat(timespec="seconds")
 
 
-class MessageContent(BaseModel):
-    type: MessageContentType = Field(..., description="The type of the message.")
-
-
-class TextContent(MessageContent):
-    type: Literal[MessageContentType.text] = Field(MessageContentType.text, description="The type of the message.")
-    text: str = Field(..., description="The text content of the message.")
-
-
-MessageContentUnion = Annotated[
-    Union[TextContent],
-    Field(discriminator="type"),
-]
-
-
 class SystemMessage(LettaMessage):
     """
     A message generated by the system. Never streamed back on a response, only used for cursor pagination.
 
-    Attributes:
-        content (Union[str, List[MessageContentUnion]]): The message content sent by the user (can be a string or an array of content parts)
+    Args:
         id (str): The ID of the message
         date (datetime): The date the message was created in ISO format
+        name (Optional[str]): The name of the sender of the message
+        content (str): The message content sent by the system
     """
 
     message_type: Literal["system_message"] = "system_message"
-    content: Union[str, List[MessageContentUnion]]
+    content: str = Field(..., description="The message content sent by the system")
 
 
 class UserMessage(LettaMessage):
     """
     A message sent by the user. Never streamed back on a response, only used for cursor pagination.
 
-    Attributes:
-        content (Union[str, List[MessageContentUnion]]): The message content sent by the user (can be a string or an array of content parts)
+    Args:
         id (str): The ID of the message
         date (datetime): The date the message was created in ISO format
+        name (Optional[str]): The name of the sender of the message
+        content (Union[str, List[LettaUserMessageContentUnion]]): The message content sent by the user (can be a string or an array of multi-modal content parts)
     """
 
     message_type: Literal["user_message"] = "user_message"
-    content: Union[str, List[MessageContentUnion]]
+    content: Union[str, List[LettaUserMessageContentUnion]] = Field(
+        ...,
+        description="The message content sent by the user (can be a string or an array of multi-modal content parts)",
+        json_schema_extra=get_letta_user_message_content_union_str_json_schema(),
+    )
 
 
 class ReasoningMessage(LettaMessage):
     """
     Representation of an agent's internal reasoning.
 
-    Attributes:
+    Args:
+        id (str): The ID of the message
+        date (datetime): The date the message was created in ISO format
+        name (Optional[str]): The name of the sender of the message
+        source (Literal["reasoner_model", "non_reasoner_model"]): Whether the reasoning
+            content was generated natively by a reasoner model or derived via prompting
         reasoning (str): The internal reasoning of the agent
+    """
+
+    message_type: Literal["reasoning_message"] = "reasoning_message"
+    source: Literal["reasoner_model", "non_reasoner_model"] = "non_reasoner_model"
+    reasoning: str
+
+
+class HiddenReasoningMessage(LettaMessage):
+    """
+    Representation of an agent's internal reasoning where reasoning content
+    has been hidden from the response.
+
+    Args:
         id (str): The ID of the message
         date (datetime): The date the message was created in ISO format
+        name (Optional[str]): The name of the sender of the message
+        state (Literal["redacted", "omitted"]): Whether the reasoning
+            content was redacted by the provider or simply omitted by the API
+        reasoning (str): The internal reasoning of the agent
     """
 
     message_type: Literal["reasoning_message"] = "reasoning_message"
+    state: Literal["redacted", "omitted"]
     reasoning: str
 
 
 class ToolCall(BaseModel):
-
     name: str
     arguments: str
     tool_call_id: str
 
 
 class ToolCallDelta(BaseModel):
-
     name: Optional[str]
     arguments: Optional[str]
     tool_call_id: Optional[str]
 
-    # NOTE: this is a workaround to exclude None values from the JSON dump,
-    # since the OpenAI style of returning chunks doesn't include keys with null values
     def model_dump(self, *args, **kwargs):
+        """
+        This is a workaround to exclude None values from the JSON dump since the
+        OpenAI style of returning chunks doesn't include keys with null values.
+        """
         kwargs["exclude_none"] = True
         return super().model_dump(*args, **kwargs)
 
@@ -118,17 +141,20 @@ class ToolCallMessage(LettaMessage):
     """
     A message representing a request to call a tool (generated by the LLM to trigger tool execution).
 
-    Attributes:
-        tool_call (Union[ToolCall, ToolCallDelta]): The tool call
+    Args:
         id (str): The ID of the message
         date (datetime): The date the message was created in ISO format
+        name (Optional[str]): The name of the sender of the message
+        tool_call (Union[ToolCall, ToolCallDelta]): The tool call
     """
 
     message_type: Literal["tool_call_message"] = "tool_call_message"
     tool_call: Union[ToolCall, ToolCallDelta]
 
-    # NOTE: this is required for the ToolCallDelta exclude_none to work correctly
     def model_dump(self, *args, **kwargs):
+        """
+        Handling for the ToolCallDelta exclude_none to work correctly
+        """
         kwargs["exclude_none"] = True
         data = super().model_dump(*args, **kwargs)
         if isinstance(data["tool_call"], dict):
@@ -141,12 +167,14 @@ class ToolCallMessage(LettaMessage):
             ToolCall: lambda v: v.model_dump(exclude_none=True),
         }
 
-    # NOTE: this is required to cast dicts into ToolCallMessage objects
-    # Without this extra validator, Pydantic will throw an error if 'name' or 'arguments' are None
-    # (instead of properly casting to ToolCallDelta instead of ToolCall)
     @field_validator("tool_call", mode="before")
     @classmethod
     def validate_tool_call(cls, v):
+        """
+        Casts dicts into ToolCallMessage objects. Without this extra validator, Pydantic will throw
+        an error if 'name' or 'arguments' are None instead of properly casting to ToolCallDelta
+        instead of ToolCall.
+        """
         if isinstance(v, dict):
             if "name" in v and "arguments" in v and "tool_call_id" in v:
                 return ToolCall(name=v["name"], arguments=v["arguments"], tool_call_id=v["tool_call_id"])
@@ -161,11 +189,12 @@ class ToolReturnMessage(LettaMessage):
     """
     A message representing the return value of a tool call (generated by Letta executing the requested tool).
 
-    Attributes:
-        tool_return (str): The return value of the tool
-        status (Literal["success", "error"]): The status of the tool call
+    Args:
         id (str): The ID of the message
         date (datetime): The date the message was created in ISO format
+        name (Optional[str]): The name of the sender of the message
+        tool_return (str): The return value of the tool
+        status (Literal["success", "error"]): The status of the tool call
         tool_call_id (str): A unique identifier for the tool call that generated this message
         stdout (Optional[List(str)]): Captured stdout (e.g. prints, logs) from the tool invocation
         stderr (Optional[List(str)]): Captured stderr from the tool invocation
@@ -179,12 +208,100 @@ class ToolReturnMessage(LettaMessage):
     stderr: Optional[List[str]] = None
 
 
-# Legacy Letta API had an additional type "assistant_message" and the "function_call" was a formatted string
+class AssistantMessage(LettaMessage):
+    """
+    A message sent by the LLM in response to user input. Used in the LLM context.
 
+    Args:
+        id (str): The ID of the message
+        date (datetime): The date the message was created in ISO format
+        name (Optional[str]): The name of the sender of the message
+        content (Union[str, List[LettaAssistantMessageContentUnion]]): The message content sent by the agent (can be a string or an array of content parts)
+    """
 
-class AssistantMessage(LettaMessage):
     message_type: Literal["assistant_message"] = "assistant_message"
-    content: Union[str, List[MessageContentUnion]]
+    content: Union[str, List[LettaAssistantMessageContentUnion]] = Field(
+        ...,
+        description="The message content sent by the agent (can be a string or an array of content parts)",
+        json_schema_extra=get_letta_assistant_message_content_union_str_json_schema(),
+    )
+
+
+# NOTE: use Pydantic's discriminated unions feature: https://docs.pydantic.dev/latest/concepts/unions/#discriminated-unions
+LettaMessageUnion = Annotated[
+    Union[SystemMessage, UserMessage, ReasoningMessage, ToolCallMessage, ToolReturnMessage, AssistantMessage],
+    Field(discriminator="message_type"),
+]
+
+
+def create_letta_message_union_schema():
+    return {
+        "oneOf": [
+            {"$ref": "#/components/schemas/SystemMessage"},
+            {"$ref": "#/components/schemas/UserMessage"},
+            {"$ref": "#/components/schemas/ReasoningMessage"},
+            {"$ref": "#/components/schemas/ToolCallMessage"},
+            {"$ref": "#/components/schemas/ToolReturnMessage"},
+            {"$ref": "#/components/schemas/AssistantMessage"},
+        ],
+        "discriminator": {
+            "propertyName": "message_type",
+            "mapping": {
+                "system_message": "#/components/schemas/SystemMessage",
+                "user_message": "#/components/schemas/UserMessage",
+                "reasoning_message": "#/components/schemas/ReasoningMessage",
+                "tool_call_message": "#/components/schemas/ToolCallMessage",
+                "tool_return_message": "#/components/schemas/ToolReturnMessage",
+                "assistant_message": "#/components/schemas/AssistantMessage",
+            },
+        },
+    }
+
+
+# --------------------------
+# Message Update API Schemas
+# --------------------------
+
+
+class UpdateSystemMessage(BaseModel):
+    message_type: Literal["system_message"] = "system_message"
+    content: str = Field(
+        ..., description="The message content sent by the system (can be a string or an array of multi-modal content parts)"
+    )
+
+
+class UpdateUserMessage(BaseModel):
+    message_type: Literal["user_message"] = "user_message"
+    content: Union[str, List[LettaUserMessageContentUnion]] = Field(
+        ...,
+        description="The message content sent by the user (can be a string or an array of multi-modal content parts)",
+        json_schema_extra=get_letta_user_message_content_union_str_json_schema(),
+    )
+
+
+class UpdateReasoningMessage(BaseModel):
+    reasoning: str
+    message_type: Literal["reasoning_message"] = "reasoning_message"
+
+
+class UpdateAssistantMessage(BaseModel):
+    message_type: Literal["assistant_message"] = "assistant_message"
+    content: Union[str, List[LettaAssistantMessageContentUnion]] = Field(
+        ...,
+        description="The message content sent by the assistant (can be a string or an array of content parts)",
+        json_schema_extra=get_letta_assistant_message_content_union_str_json_schema(),
+    )
+
+
+LettaMessageUpdateUnion = Annotated[
+    Union[UpdateSystemMessage, UpdateUserMessage, UpdateReasoningMessage, UpdateAssistantMessage],
+    Field(discriminator="message_type"),
+]
+
+
+# --------------------------
+# Deprecated Message Schemas
+# --------------------------
 
 
 class LegacyFunctionCallMessage(LettaMessage):
@@ -195,7 +312,7 @@ class LegacyFunctionReturn(LettaMessage):
     """
     A message representing the return value of a function call (generated by Letta executing the requested function).
 
-    Attributes:
+    Args:
         function_return (str): The return value of the function
         status (Literal["success", "error"]): The status of the function call
         id (str): The ID of the message
@@ -217,7 +334,7 @@ class LegacyInternalMonologue(LettaMessage):
     """
     Representation of an agent's internal monologue.
 
-    Attributes:
+    Args:
         internal_monologue (str): The internal monologue of the agent
         id (str): The ID of the message
         date (datetime): The date the message was created in ISO format
@@ -228,59 +345,3 @@ class LegacyInternalMonologue(LettaMessage):
 
 
 LegacyLettaMessage = Union[LegacyInternalMonologue, AssistantMessage, LegacyFunctionCallMessage, LegacyFunctionReturn]
-
-
-LettaMessageUnion = Annotated[
-    Union[SystemMessage, UserMessage, ReasoningMessage, ToolCallMessage, ToolReturnMessage, AssistantMessage],
-    Field(discriminator="message_type"),
-]
-
-
-class UpdateSystemMessage(BaseModel):
-    content: Union[str, List[MessageContentUnion]]
-    message_type: Literal["system_message"] = "system_message"
-
-
-class UpdateUserMessage(BaseModel):
-    content: Union[str, List[MessageContentUnion]]
-    message_type: Literal["user_message"] = "user_message"
-
-
-class UpdateReasoningMessage(BaseModel):
-    reasoning: Union[str, List[MessageContentUnion]]
-    message_type: Literal["reasoning_message"] = "reasoning_message"
-
-
-class UpdateAssistantMessage(BaseModel):
-    content: Union[str, List[MessageContentUnion]]
-    message_type: Literal["assistant_message"] = "assistant_message"
-
-
-LettaMessageUpdateUnion = Annotated[
-    Union[UpdateSystemMessage, UpdateUserMessage, UpdateReasoningMessage, UpdateAssistantMessage],
-    Field(discriminator="message_type"),
-]
-
-
-def create_letta_message_union_schema():
-    return {
-        "oneOf": [
-            {"$ref": "#/components/schemas/SystemMessage"},
-            {"$ref": "#/components/schemas/UserMessage"},
-            {"$ref": "#/components/schemas/ReasoningMessage"},
-            {"$ref": "#/components/schemas/ToolCallMessage"},
-            {"$ref": "#/components/schemas/ToolReturnMessage"},
-            {"$ref": "#/components/schemas/AssistantMessage"},
-        ],
-        "discriminator": {
-            "propertyName": "message_type",
-            "mapping": {
-                "system_message": "#/components/schemas/SystemMessage",
-                "user_message": "#/components/schemas/UserMessage",
-                "reasoning_message": "#/components/schemas/ReasoningMessage",
-                "tool_call_message": "#/components/schemas/ToolCallMessage",
-                "tool_return_message": "#/components/schemas/ToolReturnMessage",
-                "assistant_message": "#/components/schemas/AssistantMessage",
-            },
-        },
-    }

letta/schemas/letta_message_content.py

@@ -0,0 +1,192 @@
+from enum import Enum
+from typing import Annotated, Literal, Optional, Union
+
+from pydantic import BaseModel, Field
+
+
+class MessageContentType(str, Enum):
+    text = "text"
+    tool_call = "tool_call"
+    tool_return = "tool_return"
+    reasoning = "reasoning"
+    redacted_reasoning = "redacted_reasoning"
+    omitted_reasoning = "omitted_reasoning"
+
+
+class MessageContent(BaseModel):
+    type: MessageContentType = Field(..., description="The type of the message.")
+
+
+# -------------------------------
+# User Content Types
+# -------------------------------
+
+
+class TextContent(MessageContent):
+    type: Literal[MessageContentType.text] = Field(MessageContentType.text, description="The type of the message.")
+    text: str = Field(..., description="The text content of the message.")
+
+
+LettaUserMessageContentUnion = Annotated[
+    Union[TextContent],
+    Field(discriminator="type"),
+]
+
+
+def create_letta_user_message_content_union_schema():
+    return {
+        "oneOf": [
+            {"$ref": "#/components/schemas/TextContent"},
+        ],
+        "discriminator": {
+            "propertyName": "type",
+            "mapping": {
+                "text": "#/components/schemas/TextContent",
+            },
+        },
+    }
+
+
+def get_letta_user_message_content_union_str_json_schema():
+    return {
+        "anyOf": [
+            {
+                "type": "array",
+                "items": {
+                    "$ref": "#/components/schemas/LettaUserMessageContentUnion",
+                },
+            },
+            {"type": "string"},
+        ],
+    }
+
+
+# -------------------------------
+# Assistant Content Types
+# -------------------------------
+
+
+LettaAssistantMessageContentUnion = Annotated[
+    Union[TextContent],
+    Field(discriminator="type"),
+]
+
+
+def create_letta_assistant_message_content_union_schema():
+    return {
+        "oneOf": [
+            {"$ref": "#/components/schemas/TextContent"},
+        ],
+        "discriminator": {
+            "propertyName": "type",
+            "mapping": {
+                "text": "#/components/schemas/TextContent",
+            },
+        },
+    }
+
+
+def get_letta_assistant_message_content_union_str_json_schema():
+    return {
+        "anyOf": [
+            {
+                "type": "array",
+                "items": {
+                    "$ref": "#/components/schemas/LettaAssistantMessageContentUnion",
+                },
+            },
+            {"type": "string"},
+        ],
+    }
+
+
+# -------------------------------
+# Intermediate Step Content Types
+# -------------------------------
+
+
+class ToolCallContent(MessageContent):
+    type: Literal[MessageContentType.tool_call] = Field(
+        MessageContentType.tool_call, description="Indicates this content represents a tool call event."
+    )
+    id: str = Field(..., description="A unique identifier for this specific tool call instance.")
+    name: str = Field(..., description="The name of the tool being called.")
+    input: dict = Field(
+        ..., description="The parameters being passed to the tool, structured as a dictionary of parameter names to values."
+    )
+
+
+class ToolReturnContent(MessageContent):
+    type: Literal[MessageContentType.tool_return] = Field(
+        MessageContentType.tool_return, description="Indicates this content represents a tool return event."
+    )
+    tool_call_id: str = Field(..., description="References the ID of the ToolCallContent that initiated this tool call.")
+    content: str = Field(..., description="The content returned by the tool execution.")
+    is_error: bool = Field(..., description="Indicates whether the tool execution resulted in an error.")
+
+
+class ReasoningContent(MessageContent):
+    type: Literal[MessageContentType.reasoning] = Field(
+        MessageContentType.reasoning, description="Indicates this is a reasoning/intermediate step."
+    )
+    is_native: bool = Field(..., description="Whether the reasoning content was generated by a reasoner model that processed this step.")
+    reasoning: str = Field(..., description="The intermediate reasoning or thought process content.")
+    signature: Optional[str] = Field(None, description="A unique identifier for this reasoning step.")
+
+
+class RedactedReasoningContent(MessageContent):
+    type: Literal[MessageContentType.redacted_reasoning] = Field(
+        MessageContentType.redacted_reasoning, description="Indicates this is a redacted thinking step."
+    )
+    data: str = Field(..., description="The redacted or filtered intermediate reasoning content.")
+
+
+class OmittedReasoningContent(MessageContent):
+    type: Literal[MessageContentType.omitted_reasoning] = Field(
+        MessageContentType.omitted_reasoning, description="Indicates this is an omitted reasoning step."
+    )
+    tokens: int = Field(..., description="The reasoning token count for intermediate reasoning content.")
+
+
+LettaMessageContentUnion = Annotated[
+    Union[TextContent, ToolCallContent, ToolReturnContent, ReasoningContent, RedactedReasoningContent, OmittedReasoningContent],
+    Field(discriminator="type"),
+]
+
+
+def create_letta_message_content_union_schema():
+    return {
+        "oneOf": [
+            {"$ref": "#/components/schemas/TextContent"},
+            {"$ref": "#/components/schemas/ToolCallContent"},
+            {"$ref": "#/components/schemas/ToolReturnContent"},
+            {"$ref": "#/components/schemas/ReasoningContent"},
+            {"$ref": "#/components/schemas/RedactedReasoningContent"},
+            {"$ref": "#/components/schemas/OmittedReasoningContent"},
+        ],
+        "discriminator": {
+            "propertyName": "type",
+            "mapping": {
+                "text": "#/components/schemas/TextContent",
+                "tool_call": "#/components/schemas/ToolCallContent",
+                "tool_return": "#/components/schemas/ToolCallContent",
+                "reasoning": "#/components/schemas/ReasoningContent",
+                "redacted_reasoning": "#/components/schemas/RedactedReasoningContent",
+                "omitted_reasoning": "#/components/schemas/OmittedReasoningContent",
+            },
+        },
+    }
+
+
+def get_letta_message_content_union_str_json_schema():
+    return {
+        "anyOf": [
+            {
+                "type": "array",
+                "items": {
+                    "$ref": "#/components/schemas/LettaMessageContentUnion",
+                },
+            },
+            {"type": "string"},
+        ],
+    }