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

letta/round_robin_multi_agent.py

@@ -0,0 +1,152 @@
+from typing import List, Optional
+
+from letta.agent import Agent, AgentState
+from letta.interface import AgentInterface
+from letta.orm import User
+from letta.schemas.letta_message_content import TextContent
+from letta.schemas.message import Message, MessageCreate
+from letta.schemas.openai.chat_completion_response import UsageStatistics
+from letta.schemas.usage import LettaUsageStatistics
+
+
+class RoundRobinMultiAgent(Agent):
+    def __init__(
+        self,
+        interface: AgentInterface,
+        agent_state: AgentState,
+        user: User = None,
+        # custom
+        group_id: str = "",
+        agent_ids: List[str] = [],
+        description: str = "",
+        max_turns: Optional[int] = None,
+    ):
+        super().__init__(interface, agent_state, user)
+        self.group_id = group_id
+        self.agent_ids = agent_ids
+        self.description = description
+        self.max_turns = max_turns or len(agent_ids)
+
+    def step(
+        self,
+        messages: List[MessageCreate],
+        chaining: bool = True,
+        max_chaining_steps: Optional[int] = None,
+        put_inner_thoughts_first: bool = True,
+        **kwargs,
+    ) -> LettaUsageStatistics:
+        total_usage = UsageStatistics()
+        step_count = 0
+
+        token_streaming = self.interface.streaming_mode if hasattr(self.interface, "streaming_mode") else False
+        metadata = self.interface.metadata if hasattr(self.interface, "metadata") else None
+
+        agents = {}
+        for agent_id in self.agent_ids:
+            agents[agent_id] = self.load_participant_agent(agent_id=agent_id)
+
+        message_index = {}
+        chat_history: List[Message] = []
+        new_messages = messages
+        speaker_id = None
+        try:
+            for i in range(self.max_turns):
+                speaker_id = self.agent_ids[i % len(self.agent_ids)]
+                # initialize input messages
+                start_index = message_index[speaker_id] if speaker_id in message_index else 0
+                for message in chat_history[start_index:]:
+                    message.id = Message.generate_id()
+                    message.agent_id = speaker_id
+
+                for message in new_messages:
+                    chat_history.append(
+                        Message(
+                            agent_id=speaker_id,
+                            role=message.role,
+                            content=[TextContent(text=message.content)],
+                            name=message.name,
+                            model=None,
+                            tool_calls=None,
+                            tool_call_id=None,
+                            group_id=self.group_id,
+                        )
+                    )
+
+                # load agent and perform step
+                participant_agent = agents[speaker_id]
+                usage_stats = participant_agent.step(
+                    messages=chat_history[start_index:],
+                    chaining=chaining,
+                    max_chaining_steps=max_chaining_steps,
+                    stream=token_streaming,
+                    skip_verify=True,
+                    metadata=metadata,
+                    put_inner_thoughts_first=put_inner_thoughts_first,
+                )
+
+                # parse new messages for next step
+                responses = Message.to_letta_messages_from_list(participant_agent.last_response_messages)
+                assistant_messages = [response for response in responses if response.message_type == "assistant_message"]
+                new_messages = [
+                    MessageCreate(
+                        role="system",
+                        content=message.content,
+                        name=participant_agent.agent_state.name,
+                    )
+                    for message in assistant_messages
+                ]
+                message_index[speaker_id] = len(chat_history) + len(new_messages)
+
+                # sum usage
+                total_usage.prompt_tokens += usage_stats.prompt_tokens
+                total_usage.completion_tokens += usage_stats.completion_tokens
+                total_usage.total_tokens += usage_stats.total_tokens
+                step_count += 1
+
+            # persist remaining chat history
+            for message in new_messages:
+                chat_history.append(
+                    Message(
+                        agent_id=agent_id,
+                        role=message.role,
+                        content=[TextContent(text=message.content)],
+                        name=message.name,
+                        model=None,
+                        tool_calls=None,
+                        tool_call_id=None,
+                        group_id=self.group_id,
+                    )
+                )
+            for agent_id, index in message_index.items():
+                if agent_id == speaker_id:
+                    continue
+                for message in chat_history[index:]:
+                    message.id = Message.generate_id()
+                    message.agent_id = agent_id
+                self.message_manager.create_many_messages(chat_history[index:], actor=self.user)
+
+        except Exception as e:
+            raise e
+        finally:
+            self.interface.step_yield()
+
+        self.interface.step_complete()
+
+        return LettaUsageStatistics(**total_usage.model_dump(), step_count=step_count)
+
+    def load_participant_agent(self, agent_id: str) -> Agent:
+        agent_state = self.agent_manager.get_agent_by_id(agent_id=agent_id, actor=self.user)
+        persona_block = agent_state.memory.get_block(label="persona")
+        group_chat_participant_persona = (
+            "\n\n====Group Chat Contex===="
+            f"\nYou are speaking in a group chat with {len(self.agent_ids) - 1} other "
+            "agents and one user. Respond to new messages in the group chat when prompted. "
+            f"Description of the group: {self.description}"
+        )
+        agent_state.memory.update_block_value(label="persona", value=persona_block.value + group_chat_participant_persona)
+        return Agent(
+            agent_state=agent_state,
+            interface=self.interface,
+            user=self.user,
+            save_last_response=True,
+        )

letta/schemas/agent.py

@@ -7,6 +7,7 @@ from letta.constants import DEFAULT_EMBEDDING_CHUNK_SIZE
 from letta.schemas.block import CreateBlock
 from letta.schemas.embedding_config import EmbeddingConfig
 from letta.schemas.environment_variables import AgentEnvironmentVariable
+from letta.schemas.group import Group
 from letta.schemas.letta_base import OrmMetadataBase
 from letta.schemas.llm_config import LLMConfig
 from letta.schemas.memory import Memory
@@ -90,6 +91,8 @@ class AgentState(OrmMetadataBase, validate_assignment=True):
         description="If set to True, the agent will not remember previous messages (though the agent will still retain state via core memory blocks and archival/recall memory). Not recommended unless you have an advanced use case.",
     )
 
+    multi_agent_group: Optional[Group] = Field(None, description="The multi-agent group that this agent manages")
+
     def get_agent_env_vars_as_dict(self) -> Dict[str, str]:
         # Get environment variables for this agent specifically
         per_agent_env_vars = {}

letta/schemas/enums.py

@@ -9,10 +9,6 @@ class MessageRole(str, Enum):
     system = "system"
 
 
-class MessageContentType(str, Enum):
-    text = "text"
-
-
 class OptionState(str, Enum):
     """Useful for kwargs that are bool + default option"""
 

letta/schemas/group.py

@@ -0,0 +1,65 @@
+from enum import Enum
+from typing import Annotated, List, Literal, Optional, Union
+
+from pydantic import BaseModel, Field
+
+from letta.schemas.letta_base import LettaBase
+
+
+class ManagerType(str, Enum):
+    round_robin = "round_robin"
+    supervisor = "supervisor"
+    dynamic = "dynamic"
+    swarm = "swarm"
+
+
+class GroupBase(LettaBase):
+    __id_prefix__ = "group"
+
+
+class Group(GroupBase):
+    id: str = Field(..., description="The id of the group. Assigned by the database.")
+    manager_type: ManagerType = Field(..., description="")
+    agent_ids: List[str] = Field(..., description="")
+    description: str = Field(..., description="")
+    # Pattern fields
+    manager_agent_id: Optional[str] = Field(None, description="")
+    termination_token: Optional[str] = Field(None, description="")
+    max_turns: Optional[int] = Field(None, description="")
+
+
+class ManagerConfig(BaseModel):
+    manager_type: ManagerType = Field(..., description="")
+
+
+class RoundRobinManager(ManagerConfig):
+    manager_type: Literal[ManagerType.round_robin] = Field(ManagerType.round_robin, description="")
+    max_turns: Optional[int] = Field(None, description="")
+
+
+class SupervisorManager(ManagerConfig):
+    manager_type: Literal[ManagerType.supervisor] = Field(ManagerType.supervisor, description="")
+    manager_agent_id: str = Field(..., description="")
+
+
+class DynamicManager(ManagerConfig):
+    manager_type: Literal[ManagerType.dynamic] = Field(ManagerType.dynamic, description="")
+    manager_agent_id: str = Field(..., description="")
+    termination_token: Optional[str] = Field("DONE!", description="")
+    max_turns: Optional[int] = Field(None, description="")
+
+
+# class SwarmGroup(ManagerConfig):
+#   manager_type: Literal[ManagerType.swarm] = Field(ManagerType.swarm, description="")
+
+
+ManagerConfigUnion = Annotated[
+    Union[RoundRobinManager, SupervisorManager, DynamicManager],
+    Field(discriminator="manager_type"),
+]
+
+
+class GroupCreate(BaseModel):
+    agent_ids: List[str] = Field(..., description="")
+    description: str = Field(..., description="")
+    manager_config: Optional[ManagerConfigUnion] = Field(None, description="")

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",
-            },
-        },
-    }