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

letta/schemas/message.py

@@ -9,26 +9,25 @@ from typing import Any, Dict, List, Literal, Optional, Union
 
 from openai.types.chat.chat_completion_message_tool_call import ChatCompletionMessageToolCall as OpenAIToolCall
 from openai.types.chat.chat_completion_message_tool_call import Function as OpenAIFunction
-from pydantic import BaseModel, Field, field_validator, model_validator
+from pydantic import BaseModel, Field, field_validator
 
 from letta.constants import DEFAULT_MESSAGE_TOOL, DEFAULT_MESSAGE_TOOL_KWARG, TOOL_CALL_ID_MAX_LEN
 from letta.helpers.datetime_helpers import get_utc_time, is_utc_datetime
 from letta.helpers.json_helpers import json_dumps
 from letta.local_llm.constants import INNER_THOUGHTS_KWARG
-from letta.schemas.enums import MessageContentType, MessageRole
+from letta.schemas.enums import MessageRole
 from letta.schemas.letta_base import OrmMetadataBase
 from letta.schemas.letta_message import (
     AssistantMessage,
     LettaMessage,
-    MessageContentUnion,
     ReasoningMessage,
     SystemMessage,
-    TextContent,
     ToolCall,
     ToolCallMessage,
     ToolReturnMessage,
     UserMessage,
 )
+from letta.schemas.letta_message_content import LettaMessageContentUnion, TextContent, get_letta_message_content_union_str_json_schema
 from letta.system import unpack_message
 
 
@@ -66,15 +65,30 @@ class MessageCreate(BaseModel):
         MessageRole.user,
         MessageRole.system,
     ] = Field(..., description="The role of the participant.")
-    content: Union[str, List[MessageContentUnion]] = Field(..., description="The content of the message.")
+    content: Union[str, List[LettaMessageContentUnion]] = Field(
+        ...,
+        description="The content of the message.",
+        json_schema_extra=get_letta_message_content_union_str_json_schema(),
+    )
     name: Optional[str] = Field(None, description="The name of the participant.")
 
+    def model_dump(self, to_orm: bool = False, **kwargs) -> Dict[str, Any]:
+        data = super().model_dump(**kwargs)
+        if to_orm and "content" in data:
+            if isinstance(data["content"], str):
+                data["content"] = [TextContent(text=data["content"])]
+        return data
+
 
 class MessageUpdate(BaseModel):
     """Request to update a message"""
 
     role: Optional[MessageRole] = Field(None, description="The role of the participant.")
-    content: Optional[Union[str, List[MessageContentUnion]]] = Field(None, description="The content of the message.")
+    content: Optional[Union[str, List[LettaMessageContentUnion]]] = Field(
+        None,
+        description="The content of the message.",
+        json_schema_extra=get_letta_message_content_union_str_json_schema(),
+    )
     # NOTE: probably doesn't make sense to allow remapping user_id or agent_id (vs creating a new message)
     # user_id: Optional[str] = Field(None, description="The unique identifier of the user.")
     # agent_id: Optional[str] = Field(None, description="The unique identifier of the agent.")
@@ -90,12 +104,7 @@ class MessageUpdate(BaseModel):
         data = super().model_dump(**kwargs)
         if to_orm and "content" in data:
             if isinstance(data["content"], str):
-                data["text"] = data["content"]
-            else:
-                for content in data["content"]:
-                    if content["type"] == "text":
-                        data["text"] = content["text"]
-            del data["content"]
+                data["content"] = [TextContent(text=data["content"])]
         return data
 
 
@@ -119,7 +128,7 @@ class Message(BaseMessage):
 
     id: str = BaseMessage.generate_id_field()
     role: MessageRole = Field(..., description="The role of the participant.")
-    content: Optional[List[MessageContentUnion]] = Field(None, description="The content of the message.")
+    content: Optional[List[LettaMessageContentUnion]] = Field(None, description="The content of the message.")
     organization_id: Optional[str] = Field(None, description="The unique identifier of the organization.")
     agent_id: Optional[str] = Field(None, description="The unique identifier of the agent.")
     model: Optional[str] = Field(None, description="The model used to make the function call.")
@@ -129,6 +138,7 @@ class Message(BaseMessage):
     step_id: Optional[str] = Field(None, description="The id of the step that this message was created in.")
     otid: Optional[str] = Field(None, description="The offline threading id associated with this message")
     tool_returns: Optional[List[ToolReturn]] = Field(None, description="Tool execution return information for prior tool calls")
+    group_id: Optional[str] = Field(None, description="The multi-agent group that the message was sent in")
 
     # This overrides the optional base orm schema, created_at MUST exist on all messages objects
     created_at: datetime = Field(default_factory=get_utc_time, description="The timestamp when the object was created.")
@@ -140,24 +150,6 @@ class Message(BaseMessage):
         assert v in roles, f"Role must be one of {roles}"
         return v
 
-    @model_validator(mode="before")
-    @classmethod
-    def convert_from_orm(cls, data: Dict[str, Any]) -> Dict[str, Any]:
-        if isinstance(data, dict):
-            if "text" in data and "content" not in data:
-                data["content"] = [TextContent(text=data["text"])]
-                del data["text"]
-        return data
-
-    def model_dump(self, to_orm: bool = False, **kwargs) -> Dict[str, Any]:
-        data = super().model_dump(**kwargs)
-        if to_orm:
-            for content in data["content"]:
-                if content["type"] == "text":
-                    data["text"] = content["text"]
-            del data["content"]
-        return data
-
     def to_json(self):
         json_message = vars(self)
         if json_message["tool_calls"] is not None:
@@ -214,7 +206,7 @@ class Message(BaseMessage):
         assistant_message_tool_kwarg: str = DEFAULT_MESSAGE_TOOL_KWARG,
     ) -> List[LettaMessage]:
         """Convert message object (in DB format) to the style used by the original Letta API"""
-        if self.content and len(self.content) == 1 and self.content[0].type == MessageContentType.text:
+        if self.content and len(self.content) == 1 and isinstance(self.content[0], TextContent):
             text_content = self.content[0].text
         else:
             text_content = None
@@ -485,7 +477,7 @@ class Message(BaseMessage):
         """Go from Message class to ChatCompletion message object"""
 
         # TODO change to pydantic casting, eg `return SystemMessageModel(self)`
-        if self.content and len(self.content) == 1 and self.content[0].type == MessageContentType.text:
+        if self.content and len(self.content) == 1 and isinstance(self.content[0], TextContent):
             text_content = self.content[0].text
         else:
             text_content = None
@@ -560,7 +552,7 @@ class Message(BaseMessage):
         Args:
             inner_thoughts_xml_tag (str): The XML tag to wrap around inner thoughts
         """
-        if self.content and len(self.content) == 1 and self.content[0].type == MessageContentType.text:
+        if self.content and len(self.content) == 1 and isinstance(self.content[0], TextContent):
             text_content = self.content[0].text
         else:
             text_content = None
@@ -655,7 +647,7 @@ class Message(BaseMessage):
         # type Content: https://ai.google.dev/api/rest/v1/Content / https://ai.google.dev/api/rest/v1beta/Content
         #     parts[]: Part
         #     role: str ('user' or 'model')
-        if self.content and len(self.content) == 1 and self.content[0].type == MessageContentType.text:
+        if self.content and len(self.content) == 1 and isinstance(self.content[0], TextContent):
             text_content = self.content[0].text
         else:
             text_content = None
@@ -781,7 +773,7 @@ class Message(BaseMessage):
 
         # TODO: update this prompt style once guidance from Cohere on
         # embedded function calls in multi-turn conversation become more clear
-        if self.content and len(self.content) == 1 and self.content[0].type == MessageContentType.text:
+        if self.content and len(self.content) == 1 and isinstance(self.content[0], TextContent):
             text_content = self.content[0].text
         else:
             text_content = None

letta/serialize_schemas/__init__.py

@@ -1 +1 @@
-from letta.serialize_schemas.agent import SerializedAgentSchema
+from letta.serialize_schemas.marshmallow_agent import MarshmallowAgentSchema

letta/serialize_schemas/marshmallow_agent.py

@@ -0,0 +1,108 @@
+from typing import Dict
+
+from marshmallow import fields, post_dump, pre_load
+
+import letta
+from letta.orm import Agent
+from letta.schemas.agent import AgentState as PydanticAgentState
+from letta.schemas.user import User
+from letta.serialize_schemas.marshmallow_agent_environment_variable import SerializedAgentEnvironmentVariableSchema
+from letta.serialize_schemas.marshmallow_base import BaseSchema
+from letta.serialize_schemas.marshmallow_block import SerializedBlockSchema
+from letta.serialize_schemas.marshmallow_custom_fields import EmbeddingConfigField, LLMConfigField, ToolRulesField
+from letta.serialize_schemas.marshmallow_message import SerializedMessageSchema
+from letta.serialize_schemas.marshmallow_tag import SerializedAgentTagSchema
+from letta.serialize_schemas.marshmallow_tool import SerializedToolSchema
+from letta.server.db import SessionLocal
+
+
+class MarshmallowAgentSchema(BaseSchema):
+    """
+    Marshmallow schema for serializing/deserializing Agent objects.
+    Excludes relational fields.
+    """
+
+    __pydantic_model__ = PydanticAgentState
+
+    FIELD_VERSION = "version"
+    FIELD_MESSAGES = "messages"
+    FIELD_MESSAGE_IDS = "message_ids"
+    FIELD_IN_CONTEXT = "in_context"
+    FIELD_ID = "id"
+
+    llm_config = LLMConfigField()
+    embedding_config = EmbeddingConfigField()
+    tool_rules = ToolRulesField()
+
+    messages = fields.List(fields.Nested(SerializedMessageSchema))
+    core_memory = fields.List(fields.Nested(SerializedBlockSchema))
+    tools = fields.List(fields.Nested(SerializedToolSchema))
+    tool_exec_environment_variables = fields.List(fields.Nested(SerializedAgentEnvironmentVariableSchema))
+    tags = fields.List(fields.Nested(SerializedAgentTagSchema))
+
+    def __init__(self, *args, session: SessionLocal, actor: User, **kwargs):
+        super().__init__(*args, actor=actor, **kwargs)
+        self.session = session
+
+        # Propagate session and actor to nested schemas automatically
+        for field in self.fields.values():
+            if isinstance(field, fields.List) and isinstance(field.inner, fields.Nested):
+                field.inner.schema.session = session
+                field.inner.schema.actor = actor
+            elif isinstance(field, fields.Nested):
+                field.schema.session = session
+                field.schema.actor = actor
+
+    @post_dump
+    def sanitize_ids(self, data: Dict, **kwargs):
+        """
+        - Removes `message_ids`
+        - Adds versioning
+        - Marks messages as in-context
+        - Removes individual message `id` fields
+        """
+        data = super().sanitize_ids(data, **kwargs)
+        data[self.FIELD_VERSION] = letta.__version__
+
+        message_ids = set(data.pop(self.FIELD_MESSAGE_IDS, []))  # Store and remove message_ids
+
+        for message in data.get(self.FIELD_MESSAGES, []):
+            message[self.FIELD_IN_CONTEXT] = message[self.FIELD_ID] in message_ids  # Mark messages as in-context
+            message.pop(self.FIELD_ID, None)  # Remove the id field
+
+        return data
+
+    @pre_load
+    def check_version(self, data, **kwargs):
+        """Check version and remove it from the schema"""
+        version = data[self.FIELD_VERSION]
+        if version != letta.__version__:
+            print(f"Version mismatch: expected {letta.__version__}, got {version}")
+        del data[self.FIELD_VERSION]
+        return data
+
+    @pre_load
+    def remap_in_context_messages(self, data, **kwargs):
+        """
+        Restores `message_ids` by collecting message IDs where `in_context` is True,
+        generates new IDs for all messages, and removes `in_context` from all messages.
+        """
+        message_ids = []
+        for msg in data.get(self.FIELD_MESSAGES, []):
+            msg[self.FIELD_ID] = SerializedMessageSchema.generate_id()  # Generate new ID
+            if msg.pop(self.FIELD_IN_CONTEXT, False):  # If it was in-context, track its new ID
+                message_ids.append(msg[self.FIELD_ID])
+
+        data[self.FIELD_MESSAGE_IDS] = message_ids
+        return data
+
+    class Meta(BaseSchema.Meta):
+        model = Agent
+        exclude = BaseSchema.Meta.exclude + (
+            "project_id",
+            "template_id",
+            "base_template_id",
+            "sources",
+            "source_passages",
+            "agent_passages",
+        )

letta/serialize_schemas/{agent_environment_variable.py → marshmallow_agent_environment_variable.py}

@@ -2,7 +2,7 @@ import uuid
 from typing import Optional
 
 from letta.orm.sandbox_config import AgentEnvironmentVariable
-from letta.serialize_schemas.base import BaseSchema
+from letta.serialize_schemas.marshmallow_base import BaseSchema
 
 
 class SerializedAgentEnvironmentVariableSchema(BaseSchema):

letta/serialize_schemas/marshmallow_base.py

@@ -0,0 +1,52 @@
+from typing import Dict, Optional
+
+from marshmallow import post_dump, pre_load
+from marshmallow_sqlalchemy import SQLAlchemyAutoSchema
+
+from letta.schemas.user import User
+
+
+class BaseSchema(SQLAlchemyAutoSchema):
+    """
+    Base schema for all SQLAlchemy models.
+    This ensures all schemas share the same session.
+    """
+
+    __pydantic_model__ = None
+
+    def __init__(self, *args, actor: Optional[User] = None, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.actor = actor
+
+    @classmethod
+    def generate_id(cls) -> Optional[str]:
+        if cls.__pydantic_model__:
+            return cls.__pydantic_model__.generate_id()
+
+        return None
+
+    @post_dump
+    def sanitize_ids(self, data: Dict, **kwargs) -> Dict:
+        # delete id
+        del data["id"]
+        del data["_created_by_id"]
+        del data["_last_updated_by_id"]
+        del data["organization"]
+
+        return data
+
+    @pre_load
+    def regenerate_ids(self, data: Dict, **kwargs) -> Dict:
+        if self.Meta.model:
+            data["id"] = self.generate_id()
+            data["_created_by_id"] = self.actor.id
+            data["_last_updated_by_id"] = self.actor.id
+            data["organization"] = self.actor.organization_id
+
+        return data
+
+    class Meta:
+        model = None
+        include_relationships = True
+        load_instance = True
+        exclude = ()

letta/serialize_schemas/{block.py → marshmallow_block.py}

@@ -1,6 +1,6 @@
 from letta.orm.block import Block
 from letta.schemas.block import Block as PydanticBlock
-from letta.serialize_schemas.base import BaseSchema
+from letta.serialize_schemas.marshmallow_base import BaseSchema
 
 
 class SerializedBlockSchema(BaseSchema):

letta/serialize_schemas/{custom_fields.py → marshmallow_custom_fields.py}

@@ -3,10 +3,12 @@ from marshmallow import fields
 from letta.helpers.converters import (
     deserialize_embedding_config,
     deserialize_llm_config,
+    deserialize_message_content,
     deserialize_tool_calls,
     deserialize_tool_rules,
     serialize_embedding_config,
     serialize_llm_config,
+    serialize_message_content,
     serialize_tool_calls,
     serialize_tool_rules,
 )
@@ -67,3 +69,13 @@ class ToolCallField(fields.Field):
 
     def _deserialize(self, value, attr, data, **kwargs):
         return deserialize_tool_calls(value)
+
+
+class MessageContentField(fields.Field):
+    """Marshmallow field for handling a list of Message Content Part objects."""
+
+    def _serialize(self, value, attr, obj, **kwargs):
+        return serialize_message_content(value)
+
+    def _deserialize(self, value, attr, data, **kwargs):
+        return deserialize_message_content(value)

letta/serialize_schemas/marshmallow_message.py

@@ -0,0 +1,42 @@
+from typing import Dict
+
+from marshmallow import post_dump, pre_load
+
+from letta.orm.message import Message
+from letta.schemas.message import Message as PydanticMessage
+from letta.serialize_schemas.marshmallow_base import BaseSchema
+from letta.serialize_schemas.marshmallow_custom_fields import ToolCallField
+
+
+class SerializedMessageSchema(BaseSchema):
+    """
+    Marshmallow schema for serializing/deserializing Message objects.
+    """
+
+    __pydantic_model__ = PydanticMessage
+
+    tool_calls = ToolCallField()
+
+    @post_dump
+    def sanitize_ids(self, data: Dict, **kwargs) -> Dict:
+        # keep id for remapping later on agent dump
+        # agent dump will then get rid of message ids
+        del data["_created_by_id"]
+        del data["_last_updated_by_id"]
+        del data["organization"]
+
+        return data
+
+    @pre_load
+    def regenerate_ids(self, data: Dict, **kwargs) -> Dict:
+        if self.Meta.model:
+            # Skip regenerating ID, as agent dump will do it
+            data["_created_by_id"] = self.actor.id
+            data["_last_updated_by_id"] = self.actor.id
+            data["organization"] = self.actor.organization_id
+
+        return data
+
+    class Meta(BaseSchema.Meta):
+        model = Message
+        exclude = BaseSchema.Meta.exclude + ("step", "job_message", "agent", "otid", "is_deleted")

letta/serialize_schemas/{tag.py → marshmallow_tag.py}

@@ -1,7 +1,9 @@
-from marshmallow import fields
+from typing import Dict
+
+from marshmallow import fields, post_dump, pre_load
 
 from letta.orm.agents_tags import AgentsTags
-from letta.serialize_schemas.base import BaseSchema
+from letta.serialize_schemas.marshmallow_base import BaseSchema
 
 
 class SerializedAgentTagSchema(BaseSchema):
@@ -13,6 +15,14 @@ class SerializedAgentTagSchema(BaseSchema):
 
     tag = fields.String(required=True)
 
+    @post_dump
+    def sanitize_ids(self, data: Dict, **kwargs):
+        return data
+
+    @pre_load
+    def regenerate_ids(self, data: Dict, **kwargs) -> Dict:
+        return data
+
     class Meta(BaseSchema.Meta):
         model = AgentsTags
         exclude = BaseSchema.Meta.exclude + ("agent",)

letta/serialize_schemas/{tool.py → marshmallow_tool.py}

@@ -1,6 +1,6 @@
 from letta.orm import Tool
 from letta.schemas.tool import Tool as PydanticTool
-from letta.serialize_schemas.base import BaseSchema
+from letta.serialize_schemas.marshmallow_base import BaseSchema
 
 
 class SerializedToolSchema(BaseSchema):

letta/serialize_schemas/pydantic_agent_schema.py

@@ -0,0 +1,111 @@
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field
+
+from letta.schemas.embedding_config import EmbeddingConfig
+from letta.schemas.letta_message_content import TextContent
+from letta.schemas.llm_config import LLMConfig
+
+
+class CoreMemoryBlockSchema(BaseModel):
+    created_at: str
+    description: Optional[str]
+    identities: List[Any]
+    is_deleted: bool
+    is_template: bool
+    label: str
+    limit: int
+    metadata_: Dict[str, Any] = Field(default_factory=dict)
+    template_name: Optional[str]
+    updated_at: str
+    value: str
+
+
+class MessageSchema(BaseModel):
+    created_at: str
+    group_id: Optional[str]
+    in_context: bool
+    model: Optional[str]
+    name: Optional[str]
+    role: str
+    content: List[TextContent]  # TODO: Expand to more in the future
+    tool_call_id: Optional[str]
+    tool_calls: List[Any]
+    tool_returns: List[Any]
+    updated_at: str
+
+
+class TagSchema(BaseModel):
+    tag: str
+
+
+class ToolEnvVarSchema(BaseModel):
+    created_at: str
+    description: Optional[str]
+    is_deleted: bool
+    key: str
+    updated_at: str
+    value: str
+
+
+class ToolRuleSchema(BaseModel):
+    tool_name: str
+    type: str
+
+
+class ParameterProperties(BaseModel):
+    type: str
+    description: Optional[str] = None
+
+
+class ParametersSchema(BaseModel):
+    type: Optional[str] = "object"
+    properties: Dict[str, ParameterProperties]
+    required: List[str] = Field(default_factory=list)
+
+
+class ToolJSONSchema(BaseModel):
+    name: str
+    description: str
+    parameters: ParametersSchema  # <— nested strong typing
+    type: Optional[str] = None  # top-level 'type' if it exists
+    required: Optional[List[str]] = Field(default_factory=list)
+
+
+class ToolSchema(BaseModel):
+    args_json_schema: Optional[Any]
+    created_at: str
+    description: str
+    is_deleted: bool
+    json_schema: ToolJSONSchema
+    name: str
+    return_char_limit: int
+    source_code: Optional[str]
+    source_type: str
+    tags: List[str]
+    tool_type: str
+    updated_at: str
+
+
+class AgentSchema(BaseModel):
+    agent_type: str
+    core_memory: List[CoreMemoryBlockSchema]
+    created_at: str
+    description: str
+    embedding_config: EmbeddingConfig
+    groups: List[Any]
+    identities: List[Any]
+    is_deleted: bool
+    llm_config: LLMConfig
+    message_buffer_autoclear: bool
+    messages: List[MessageSchema]
+    metadata_: Dict
+    multi_agent_group: Optional[Any]
+    name: str
+    system: str
+    tags: List[TagSchema]
+    tool_exec_environment_variables: List[ToolEnvVarSchema]
+    tool_rules: List[ToolRuleSchema]
+    tools: List[ToolSchema]
+    updated_at: str
+    version: str

letta/server/rest_api/app.py

@@ -17,6 +17,11 @@ from letta.errors import BedrockPermissionError, LettaAgentNotFoundError, LettaU
 from letta.log import get_logger
 from letta.orm.errors import DatabaseTimeoutError, ForeignKeyConstraintViolationError, NoResultFound, UniqueConstraintViolationError
 from letta.schemas.letta_message import create_letta_message_union_schema
+from letta.schemas.letta_message_content import (
+    create_letta_assistant_message_content_union_schema,
+    create_letta_message_content_union_schema,
+    create_letta_user_message_content_union_schema,
+)
 from letta.server.constants import REST_DEFAULT_PORT
 
 # NOTE(charles): these are extra routes that are not part of v1 but we still need to mount to pass tests
@@ -68,6 +73,10 @@ def generate_openapi_schema(app: FastAPI):
     letta_docs["paths"] = {k: v for k, v in letta_docs["paths"].items() if not k.startswith("/openai")}
     letta_docs["info"]["title"] = "Letta API"
     letta_docs["components"]["schemas"]["LettaMessageUnion"] = create_letta_message_union_schema()
+    letta_docs["components"]["schemas"]["LettaMessageContentUnion"] = create_letta_message_content_union_schema()
+    letta_docs["components"]["schemas"]["LettaAssistantMessageContentUnion"] = create_letta_assistant_message_content_union_schema()
+    letta_docs["components"]["schemas"]["LettaUserMessageContentUnion"] = create_letta_user_message_content_union_schema()
+
     for name, docs in [
         (
             "letta",
@@ -320,6 +329,9 @@ def start_server(
             app,
             host=host or "localhost",
             port=port or REST_DEFAULT_PORT,
+            workers=settings.uvicorn_workers,
+            reload=settings.uvicorn_reload,
+            timeout_keep_alive=settings.uvicorn_timeout_keep_alive,
             ssl_keyfile="certs/localhost-key.pem",
             ssl_certfile="certs/localhost.pem",
         )
@@ -336,4 +348,7 @@ def start_server(
             app,
             host=host or "localhost",
             port=port or REST_DEFAULT_PORT,
+            workers=settings.uvicorn_workers,
+            reload=settings.uvicorn_reload,
+            timeout_keep_alive=settings.uvicorn_timeout_keep_alive,
         )

letta/server/rest_api/routers/v1/__init__.py

@@ -1,5 +1,6 @@
 from letta.server.rest_api.routers.v1.agents import router as agents_router
 from letta.server.rest_api.routers.v1.blocks import router as blocks_router
+from letta.server.rest_api.routers.v1.groups import router as groups_router
 from letta.server.rest_api.routers.v1.health import router as health_router
 from letta.server.rest_api.routers.v1.identities import router as identities_router
 from letta.server.rest_api.routers.v1.jobs import router as jobs_router
@@ -17,6 +18,7 @@ ROUTERS = [
     tools_router,
     sources_router,
     agents_router,
+    groups_router,
     identities_router,
     llm_router,
     blocks_router,