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

letta/functions/mcp_client/stdio_client.py

@@ -0,0 +1,103 @@
+import sys
+from contextlib import asynccontextmanager
+
+import anyio
+import anyio.lowlevel
+import mcp.types as types
+from anyio.streams.text import TextReceiveStream
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import get_default_environment
+
+from letta.functions.mcp_client.base_client import BaseMCPClient
+from letta.functions.mcp_client.types import StdioServerConfig
+from letta.log import get_logger
+
+logger = get_logger(__name__)
+
+
+class StdioMCPClient(BaseMCPClient):
+    def _initialize_connection(self, server_config: StdioServerConfig) -> bool:
+        try:
+            server_params = StdioServerParameters(command=server_config.command, args=server_config.args)
+            stdio_cm = forked_stdio_client(server_params)
+            stdio_transport = self.loop.run_until_complete(stdio_cm.__aenter__())
+            self.stdio, self.write = stdio_transport
+            self.cleanup_funcs.append(lambda: self.loop.run_until_complete(stdio_cm.__aexit__(None, None, None)))
+
+            session_cm = ClientSession(self.stdio, self.write)
+            self.session = self.loop.run_until_complete(session_cm.__aenter__())
+            self.cleanup_funcs.append(lambda: self.loop.run_until_complete(session_cm.__aexit__(None, None, None)))
+            return True
+        except Exception:
+            return False
+
+
+@asynccontextmanager
+async def forked_stdio_client(server: StdioServerParameters):
+    """
+    Client transport for stdio: this will connect to a server by spawning a
+    process and communicating with it over stdin/stdout.
+    """
+    read_stream_writer, read_stream = anyio.create_memory_object_stream(0)
+    write_stream, write_stream_reader = anyio.create_memory_object_stream(0)
+
+    try:
+        process = await anyio.open_process(
+            [server.command, *server.args],
+            env=server.env or get_default_environment(),
+            stderr=sys.stderr,  # Consider logging stderr somewhere instead of silencing it
+        )
+    except OSError as exc:
+        raise RuntimeError(f"Failed to spawn process: {server.command} {server.args}") from exc
+
+    async def stdout_reader():
+        assert process.stdout, "Opened process is missing stdout"
+        buffer = ""
+        try:
+            async with read_stream_writer:
+                async for chunk in TextReceiveStream(
+                    process.stdout,
+                    encoding=server.encoding,
+                    errors=server.encoding_error_handler,
+                ):
+                    lines = (buffer + chunk).split("\n")
+                    buffer = lines.pop()
+                    for line in lines:
+                        try:
+                            message = types.JSONRPCMessage.model_validate_json(line)
+                        except Exception as exc:
+                            await read_stream_writer.send(exc)
+                            continue
+                        await read_stream_writer.send(message)
+        except anyio.ClosedResourceError:
+            await anyio.lowlevel.checkpoint()
+
+    async def stdin_writer():
+        assert process.stdin, "Opened process is missing stdin"
+        try:
+            async with write_stream_reader:
+                async for message in write_stream_reader:
+                    json = message.model_dump_json(by_alias=True, exclude_none=True)
+                    await process.stdin.send(
+                        (json + "\n").encode(
+                            encoding=server.encoding,
+                            errors=server.encoding_error_handler,
+                        )
+                    )
+        except anyio.ClosedResourceError:
+            await anyio.lowlevel.checkpoint()
+
+    async def watch_process_exit():
+        returncode = await process.wait()
+        if returncode != 0:
+            raise RuntimeError(f"Subprocess exited with code {returncode}. Command: {server.command} {server.args}")
+
+    async with anyio.create_task_group() as tg, process:
+        tg.start_soon(stdout_reader)
+        tg.start_soon(stdin_writer)
+        tg.start_soon(watch_process_exit)
+
+        with anyio.move_on_after(0.2):
+            await anyio.sleep_forever()
+
+        yield read_stream, write_stream

letta/functions/mcp_client/types.py

@@ -0,0 +1,48 @@
+from enum import Enum
+from typing import List, Optional
+
+from mcp import Tool
+from pydantic import BaseModel, Field
+
+
+class MCPTool(Tool):
+    """A simple wrapper around MCP's tool definition (to avoid conflict with our own)"""
+
+
+class MCPServerType(str, Enum):
+    SSE = "sse"
+    STDIO = "stdio"
+
+
+class BaseServerConfig(BaseModel):
+    server_name: str = Field(..., description="The name of the server")
+    type: MCPServerType
+
+
+class SSEServerConfig(BaseServerConfig):
+    type: MCPServerType = MCPServerType.SSE
+    server_url: str = Field(..., description="The URL of the server (MCP SSE client will connect to this URL)")
+
+    def to_dict(self) -> dict:
+        values = {
+            "transport": "sse",
+            "url": self.server_url,
+        }
+        return values
+
+
+class StdioServerConfig(BaseServerConfig):
+    type: MCPServerType = MCPServerType.STDIO
+    command: str = Field(..., description="The command to run (MCP 'local' client will run this command)")
+    args: List[str] = Field(..., description="The arguments to pass to the command")
+    env: Optional[dict[str, str]] = Field(None, description="Environment variables to set")
+
+    def to_dict(self) -> dict:
+        values = {
+            "transport": "stdio",
+            "command": self.command,
+            "args": self.args,
+        }
+        if self.env is not None:
+            values["env"] = self.env
+        return values

letta/functions/schema_generator.py

@@ -6,7 +6,7 @@ from composio.client.collections import ActionParametersModel
 from docstring_parser import parse
 from pydantic import BaseModel
 
-from letta.helpers.mcp_helpers import MCPTool
+from letta.functions.mcp_client.types import MCPTool
 
 
 def is_optional(annotation):

letta/helpers/converters.py

@@ -8,6 +8,16 @@ from sqlalchemy import Dialect
 
 from letta.schemas.embedding_config import EmbeddingConfig
 from letta.schemas.enums import ToolRuleType
+from letta.schemas.letta_message_content import (
+    MessageContent,
+    MessageContentType,
+    OmittedReasoningContent,
+    ReasoningContent,
+    RedactedReasoningContent,
+    TextContent,
+    ToolCallContent,
+    ToolReturnContent,
+)
 from letta.schemas.llm_config import LLMConfig
 from letta.schemas.message import ToolReturn
 from letta.schemas.tool_rule import ChildToolRule, ConditionalToolRule, ContinueToolRule, InitToolRule, TerminalToolRule, ToolRule
@@ -80,10 +90,13 @@ def deserialize_tool_rule(data: Dict) -> Union[ChildToolRule, InitToolRule, Term
     rule_type = ToolRuleType(data.get("type"))
 
     if rule_type == ToolRuleType.run_first or rule_type == ToolRuleType.InitToolRule:
+        data["type"] = ToolRuleType.run_first
         return InitToolRule(**data)
     elif rule_type == ToolRuleType.exit_loop or rule_type == ToolRuleType.TerminalToolRule:
+        data["type"] = ToolRuleType.exit_loop
         return TerminalToolRule(**data)
     elif rule_type == ToolRuleType.constrain_child_tools or rule_type == ToolRuleType.ToolRule:
+        data["type"] = ToolRuleType.constrain_child_tools
         return ChildToolRule(**data)
     elif rule_type == ToolRuleType.conditional:
         return ConditionalToolRule(**data)
@@ -163,6 +176,60 @@ def deserialize_tool_returns(data: Optional[List[Dict]]) -> List[ToolReturn]:
     return tool_returns
 
 
+# ----------------------------
+# MessageContent Serialization
+# ----------------------------
+
+
+def serialize_message_content(message_content: Optional[List[Union[MessageContent, dict]]]) -> List[Dict]:
+    """Convert a list of MessageContent objects into JSON-serializable format."""
+    if not message_content:
+        return []
+
+    serialized_message_content = []
+    for content in message_content:
+        if isinstance(content, MessageContent):
+            serialized_message_content.append(content.model_dump())
+        elif isinstance(content, dict):
+            serialized_message_content.append(content)  # Already a dictionary, leave it as-is
+        else:
+            raise TypeError(f"Unexpected message content type: {type(content)}")
+
+    return serialized_message_content
+
+
+def deserialize_message_content(data: Optional[List[Dict]]) -> List[MessageContent]:
+    """Convert a JSON list back into MessageContent objects."""
+    if not data:
+        return []
+
+    message_content = []
+    for item in data:
+        if not item:
+            continue
+
+        content_type = item.get("type")
+        if content_type == MessageContentType.text:
+            content = TextContent(**item)
+        elif content_type == MessageContentType.tool_call:
+            content = ToolCallContent(**item)
+        elif content_type == MessageContentType.tool_return:
+            content = ToolReturnContent(**item)
+        elif content_type == MessageContentType.reasoning:
+            content = ReasoningContent(**item)
+        elif content_type == MessageContentType.redacted_reasoning:
+            content = RedactedReasoningContent(**item)
+        elif content_type == MessageContentType.omitted_reasoning:
+            content = OmittedReasoningContent(**item)
+        else:
+            # Skip invalid content
+            continue
+
+        message_content.append(content)
+
+    return message_content
+
+
 # --------------------------
 # Vector Serialization
 # --------------------------

letta/llm_api/openai.py

@@ -221,7 +221,7 @@ def openai_chat_completions_process_stream(
     # TODO(sarah): add message ID generation function
     dummy_message = _Message(
         role=_MessageRole.assistant,
-        text="",
+        content=[],
         agent_id="",
         model="",
         name=None,

letta/memory.py

@@ -5,8 +5,9 @@ from letta.llm_api.llm_api_tools import create
 from letta.prompts.gpt_summarize import SYSTEM as SUMMARY_PROMPT_SYSTEM
 from letta.schemas.agent import AgentState
 from letta.schemas.enums import MessageRole
+from letta.schemas.letta_message_content import TextContent
 from letta.schemas.memory import Memory
-from letta.schemas.message import Message, TextContent
+from letta.schemas.message import Message
 from letta.settings import summarizer_settings
 from letta.utils import count_tokens, printd
 

letta/orm/__init__.py

@@ -4,6 +4,8 @@ from letta.orm.base import Base
 from letta.orm.block import Block
 from letta.orm.blocks_agents import BlocksAgents
 from letta.orm.file import FileMetadata
+from letta.orm.group import Group
+from letta.orm.groups_agents import GroupsAgents
 from letta.orm.identities_agents import IdentitiesAgents
 from letta.orm.identities_blocks import IdentitiesBlocks
 from letta.orm.identity import Identity

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