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

letta/orm/agent.py

@@ -1,5 +1,5 @@
 import uuid
-from typing import TYPE_CHECKING, List, Optional
+from typing import TYPE_CHECKING, List, Optional, Set
 
 from sqlalchemy import JSON, Boolean, Index, String
 from sqlalchemy.orm import Mapped, mapped_column, relationship
@@ -128,37 +128,86 @@ class Agent(SqlalchemyBase, OrganizationMixin):
         back_populates="agents",
         passive_deletes=True,
     )
+    groups: Mapped[List["Group"]] = relationship(
+        "Group",
+        secondary="groups_agents",
+        lazy="selectin",
+        back_populates="agents",
+        passive_deletes=True,
+    )
+    multi_agent_group: Mapped["Group"] = relationship(
+        "Group",
+        lazy="joined",
+        viewonly=True,
+        back_populates="manager_agent",
+    )
+
+    def to_pydantic(self, include_relationships: Optional[Set[str]] = None) -> PydanticAgentState:
+        """
+        Converts the SQLAlchemy Agent model into its Pydantic counterpart.
+
+        The following base fields are always included:
+          - id, agent_type, name, description, system, message_ids, metadata_,
+            llm_config, embedding_config, project_id, template_id, base_template_id,
+            tool_rules, message_buffer_autoclear, tags
 
-    def to_pydantic(self) -> PydanticAgentState:
-        """converts to the basic pydantic model counterpart"""
-        # add default rule for having send_message be a terminal tool
-        tool_rules = self.tool_rules
+        Everything else (e.g., tools, sources, memory, etc.) is optional and only
+        included if specified in `include_fields`.
+
+        Args:
+            include_relationships (Optional[Set[str]]):
+                A set of additional field names to include in the output. If None or empty,
+                no extra fields are loaded beyond the base fields.
+
+        Returns:
+            PydanticAgentState: The Pydantic representation of the agent.
+        """
+        # Base fields: always included
         state = {
             "id": self.id,
-            "organization_id": self.organization_id,
+            "agent_type": self.agent_type,
             "name": self.name,
             "description": self.description,
-            "message_ids": self.message_ids,
-            "tools": self.tools,
-            "sources": [source.to_pydantic() for source in self.sources],
-            "tags": [t.tag for t in self.tags],
-            "tool_rules": tool_rules,
             "system": self.system,
-            "agent_type": self.agent_type,
+            "message_ids": self.message_ids,
+            "metadata": self.metadata_,  # Exposed as 'metadata' to Pydantic
             "llm_config": self.llm_config,
             "embedding_config": self.embedding_config,
-            "metadata": self.metadata_,
-            "memory": Memory(blocks=[b.to_pydantic() for b in self.core_memory]),
-            "created_by_id": self.created_by_id,
-            "last_updated_by_id": self.last_updated_by_id,
-            "created_at": self.created_at,
-            "updated_at": self.updated_at,
-            "tool_exec_environment_variables": self.tool_exec_environment_variables,
             "project_id": self.project_id,
             "template_id": self.template_id,
             "base_template_id": self.base_template_id,
-            "identity_ids": [identity.id for identity in self.identities],
+            "tool_rules": self.tool_rules,
             "message_buffer_autoclear": self.message_buffer_autoclear,
+            "created_by_id": self.created_by_id,
+            "last_updated_by_id": self.last_updated_by_id,
+            "created_at": self.created_at,
+            "updated_at": self.updated_at,
+            # optional field defaults
+            "tags": [],
+            "tools": [],
+            "sources": [],
+            "memory": Memory(blocks=[]),
+            "identity_ids": [],
+            "multi_agent_group": None,
+            "tool_exec_environment_variables": [],
+        }
+
+        # Optional fields: only included if requested
+        optional_fields = {
+            "tags": lambda: [t.tag for t in self.tags],
+            "tools": lambda: self.tools,
+            "sources": lambda: [s.to_pydantic() for s in self.sources],
+            "memory": lambda: Memory(blocks=[b.to_pydantic() for b in self.core_memory]),
+            "identity_ids": lambda: [i.id for i in self.identities],
+            "multi_agent_group": lambda: self.multi_agent_group,
+            "tool_exec_environment_variables": lambda: self.tool_exec_environment_variables,
         }
 
+        include_relationships = set(optional_fields.keys() if include_relationships is None else include_relationships)
+
+        for field_name in include_relationships:
+            resolver = optional_fields.get(field_name)
+            if resolver:
+                state[field_name] = resolver()
+
         return self.__pydantic_model__(**state)

letta/orm/custom_columns.py

@@ -4,12 +4,14 @@ from sqlalchemy.types import BINARY, TypeDecorator
 from letta.helpers.converters import (
     deserialize_embedding_config,
     deserialize_llm_config,
+    deserialize_message_content,
     deserialize_tool_calls,
     deserialize_tool_returns,
     deserialize_tool_rules,
     deserialize_vector,
     serialize_embedding_config,
     serialize_llm_config,
+    serialize_message_content,
     serialize_tool_calls,
     serialize_tool_returns,
     serialize_tool_rules,
@@ -82,6 +84,19 @@ class ToolReturnColumn(TypeDecorator):
         return deserialize_tool_returns(value)
 
 
+class MessageContentColumn(TypeDecorator):
+    """Custom SQLAlchemy column type for storing the content parts of a message as JSON."""
+
+    impl = JSON
+    cache_ok = True
+
+    def process_bind_param(self, value, dialect):
+        return serialize_message_content(value)
+
+    def process_result_value(self, value, dialect):
+        return deserialize_message_content(value)
+
+
 class CommonVector(TypeDecorator):
     """Custom SQLAlchemy column type for storing vectors in SQLite."""
 

letta/orm/group.py

@@ -0,0 +1,33 @@
+import uuid
+from typing import List, Optional
+
+from sqlalchemy import ForeignKey, String
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from letta.orm.mixins import OrganizationMixin
+from letta.orm.sqlalchemy_base import SqlalchemyBase
+from letta.schemas.group import Group as PydanticGroup
+
+
+class Group(SqlalchemyBase, OrganizationMixin):
+
+    __tablename__ = "groups"
+    __pydantic_model__ = PydanticGroup
+
+    id: Mapped[str] = mapped_column(String, primary_key=True, default=lambda: f"group-{uuid.uuid4()}")
+    description: Mapped[str] = mapped_column(nullable=False, doc="")
+    manager_type: Mapped[str] = mapped_column(nullable=False, doc="")
+    manager_agent_id: Mapped[Optional[str]] = mapped_column(String, ForeignKey("agents.id", ondelete="RESTRICT"), nullable=True, doc="")
+    termination_token: Mapped[Optional[str]] = mapped_column(nullable=True, doc="")
+    max_turns: Mapped[Optional[int]] = mapped_column(nullable=True, doc="")
+
+    # relationships
+    organization: Mapped["Organization"] = relationship("Organization", back_populates="groups")
+    agents: Mapped[List["Agent"]] = relationship(
+        "Agent", secondary="groups_agents", lazy="selectin", passive_deletes=True, back_populates="groups"
+    )
+    manager_agent: Mapped["Agent"] = relationship("Agent", lazy="joined", back_populates="multi_agent_group")
+
+    @property
+    def agent_ids(self) -> List[str]:
+        return [agent.id for agent in self.agents]

letta/orm/groups_agents.py

@@ -0,0 +1,13 @@
+from sqlalchemy import ForeignKey, String
+from sqlalchemy.orm import Mapped, mapped_column
+
+from letta.orm.base import Base
+
+
+class GroupsAgents(Base):
+    """Agents may have one or many groups associated with them."""
+
+    __tablename__ = "groups_agents"
+
+    group_id: Mapped[str] = mapped_column(String, ForeignKey("groups.id", ondelete="CASCADE"), primary_key=True)
+    agent_id: Mapped[str] = mapped_column(String, ForeignKey("agents.id", ondelete="CASCADE"), primary_key=True)

letta/orm/message.py

@@ -4,11 +4,12 @@ from openai.types.chat.chat_completion_message_tool_call import ChatCompletionMe
 from sqlalchemy import ForeignKey, Index
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 
-from letta.orm.custom_columns import ToolCallColumn, ToolReturnColumn
+from letta.orm.custom_columns import MessageContentColumn, ToolCallColumn, ToolReturnColumn
 from letta.orm.mixins import AgentMixin, OrganizationMixin
 from letta.orm.sqlalchemy_base import SqlalchemyBase
+from letta.schemas.letta_message_content import MessageContent
+from letta.schemas.letta_message_content import TextContent as PydanticTextContent
 from letta.schemas.message import Message as PydanticMessage
-from letta.schemas.message import TextContent as PydanticTextContent
 from letta.schemas.message import ToolReturn
 
 
@@ -25,6 +26,7 @@ class Message(SqlalchemyBase, OrganizationMixin, AgentMixin):
     id: Mapped[str] = mapped_column(primary_key=True, doc="Unique message identifier")
     role: Mapped[str] = mapped_column(doc="Message role (user/assistant/system/tool)")
     text: Mapped[Optional[str]] = mapped_column(nullable=True, doc="Message content")
+    content: Mapped[List[MessageContent]] = mapped_column(MessageContentColumn, nullable=True, doc="Message content parts")
     model: Mapped[Optional[str]] = mapped_column(nullable=True, doc="LLM model used")
     name: Mapped[Optional[str]] = mapped_column(nullable=True, doc="Name for multi-agent scenarios")
     tool_calls: Mapped[List[OpenAIToolCall]] = mapped_column(ToolCallColumn, doc="Tool call information")
@@ -36,6 +38,7 @@ class Message(SqlalchemyBase, OrganizationMixin, AgentMixin):
     tool_returns: Mapped[List[ToolReturn]] = mapped_column(
         ToolReturnColumn, nullable=True, doc="Tool execution return information for prior tool calls"
     )
+    group_id: Mapped[Optional[str]] = mapped_column(nullable=True, doc="The multi-agent group that the message was sent in")
 
     # Relationships
     agent: Mapped["Agent"] = relationship("Agent", back_populates="messages", lazy="selectin")
@@ -53,8 +56,8 @@ class Message(SqlalchemyBase, OrganizationMixin, AgentMixin):
         return self.job_message.job if self.job_message else None
 
     def to_pydantic(self) -> PydanticMessage:
-        """custom pydantic conversion for message content mapping"""
+        """Custom pydantic conversion to handle data using legacy text field"""
         model = self.__pydantic_model__.model_validate(self)
-        if self.text:
+        if self.text and not model.content:
             model.content = [PydanticTextContent(text=self.text)]
         return model

letta/orm/organization.py

@@ -49,6 +49,7 @@ class Organization(SqlalchemyBase):
     agent_passages: Mapped[List["AgentPassage"]] = relationship("AgentPassage", back_populates="organization", cascade="all, delete-orphan")
     providers: Mapped[List["Provider"]] = relationship("Provider", back_populates="organization", cascade="all, delete-orphan")
     identities: Mapped[List["Identity"]] = relationship("Identity", back_populates="organization", cascade="all, delete-orphan")
+    groups: Mapped[List["Group"]] = relationship("Group", back_populates="organization", cascade="all, delete-orphan")
 
     @property
     def passages(self) -> List[Union["SourcePassage", "AgentPassage"]]:

letta/orm/sqlalchemy_base.py

@@ -139,11 +139,11 @@ class SqlalchemyBase(CommonSqlalchemyMetaMixins, Base):
                 else:
                     # Match ANY tag - use join and filter
                     query = (
-                        query.join(cls.tags).filter(cls.tags.property.mapper.class_.tag.in_(tags)).group_by(cls.id)
+                        query.join(cls.tags).filter(cls.tags.property.mapper.class_.tag.in_(tags)).distinct(cls.id).order_by(cls.id)
                     )  # Deduplicate results
 
-                # Group by primary key and all necessary columns to avoid JSON comparison
-                query = query.group_by(cls.id)
+                # select distinct primary key
+                query = query.distinct(cls.id).order_by(cls.id)
 
             if identifier_keys and hasattr(cls, "identities"):
                 query = query.join(cls.identities).filter(cls.identities.property.mapper.class_.identifier_key.in_(identifier_keys))

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="")