letta-nightly 0.12.1.dev20251023104211__py3-none-any.whl → 0.13.0.dev20251024223017__py3-none-any.whl

letta/schemas/letta_message.py

@@ -17,6 +17,34 @@ from letta.schemas.letta_message_content import (
 # ---------------------------
 
 
+class MessageReturnType(str, Enum):
+    approval = "approval"
+    tool = "tool"
+
+
+class MessageReturn(BaseModel):
+    type: MessageReturnType = Field(..., description="The message type to be created.")
+
+
+class ApprovalReturn(MessageReturn):
+    type: Literal[MessageReturnType.approval] = Field(default=MessageReturnType.approval, description="The message type to be created.")
+    tool_call_id: str = Field(..., description="The ID of the tool call that corresponds to this approval")
+    approve: bool = Field(..., description="Whether the tool has been approved")
+    reason: Optional[str] = Field(None, description="An optional explanation for the provided approval status")
+
+
+class ToolReturn(MessageReturn):
+    type: Literal[MessageReturnType.tool] = Field(default=MessageReturnType.tool, description="The message type to be created.")
+    tool_return: str
+    status: Literal["success", "error"]
+    tool_call_id: str
+    stdout: Optional[List[str]] = None
+    stderr: Optional[List[str]] = None
+
+
+LettaMessageReturnUnion = Annotated[Union[ApprovalReturn, ToolReturn], Field(discriminator="type")]
+
+
 class MessageType(str, Enum):
     system_message = "system_message"
     user_message = "user_message"
@@ -233,14 +261,6 @@ class ToolCallMessage(LettaMessage):
         return v
 
 
-class ToolReturn(BaseModel):
-    tool_return: str
-    status: Literal["success", "error"]
-    tool_call_id: str
-    stdout: Optional[List[str]] = None
-    stderr: Optional[List[str]] = None
-
-
 class ToolReturnMessage(LettaMessage):
     """
     A message representing the return value of a tool call (generated by Letta executing the requested tool).
@@ -282,7 +302,12 @@ class ApprovalRequestMessage(LettaMessage):
     message_type: Literal[MessageType.approval_request_message] = Field(
         default=MessageType.approval_request_message, description="The type of the message."
     )
-    tool_call: Union[ToolCall, ToolCallDelta] = Field(..., description="The tool call that has been requested by the llm to run")
+    tool_call: Union[ToolCall, ToolCallDelta] = Field(
+        ..., description="The tool call that has been requested by the llm to run", deprecated=True
+    )
+    tool_calls: Optional[Union[List[ToolCall], ToolCallDelta]] = Field(
+        None, description="The tool calls that have been requested by the llm to run, which are pending approval"
+    )
 
 
 class ApprovalResponseMessage(LettaMessage):
@@ -301,9 +326,10 @@ class ApprovalResponseMessage(LettaMessage):
     message_type: Literal[MessageType.approval_response_message] = Field(
         default=MessageType.approval_response_message, description="The type of the message."
     )
-    approve: bool = Field(..., description="Whether the tool has been approved")
-    approval_request_id: str = Field(..., description="The message ID of the approval request")
-    reason: Optional[str] = Field(None, description="An optional explanation for the provided approval status")
+    approvals: Optional[List[LettaMessageReturnUnion]] = Field(default=None, description="The list of approval responses")
+    approve: Optional[bool] = Field(None, description="Whether the tool has been approved", deprecated=True)
+    approval_request_id: Optional[str] = Field(None, description="The message ID of the approval request", deprecated=True)
+    reason: Optional[str] = Field(None, description="An optional explanation for the provided approval status", deprecated=True)
 
 
 class AssistantMessage(LettaMessage):
@@ -327,6 +353,21 @@ class AssistantMessage(LettaMessage):
     )
 
 
+class LettaPing(LettaMessage):
+    """
+    A ping message used as a keepalive to prevent SSE streams from timing out during long running requests.
+
+    Args:
+        id (str): The ID of the message
+        date (datetime): The date the message was created in ISO format
+    """
+
+    message_type: Literal["ping"] = Field(
+        "ping",
+        description="The type of the message. Ping messages are a keep-alive to prevent SSE streams from timing out during long running requests.",
+    )
+
+
 # NOTE: use Pydantic's discriminated unions feature: https://docs.pydantic.dev/latest/concepts/unions/#discriminated-unions
 LettaMessageUnion = Annotated[
     Union[
@@ -374,6 +415,24 @@ def create_letta_message_union_schema():
     }
 
 
+def create_letta_ping_schema():
+    return {
+        "properties": {
+            "message_type": {
+                "type": "string",
+                "const": "ping",
+                "title": "Message Type",
+                "description": "The type of the message.",
+                "default": "ping",
+            }
+        },
+        "type": "object",
+        "required": ["message_type"],
+        "title": "LettaPing",
+        "description": "Ping messages are a keep-alive to prevent SSE streams from timing out during long running requests.",
+    }
+
+
 # --------------------------
 # Message Update API Schemas
 # --------------------------

letta/schemas/letta_request.py

@@ -15,15 +15,18 @@ class LettaRequest(BaseModel):
     )
     use_assistant_message: bool = Field(
         default=True,
-        description="Whether the server should parse specific tool call arguments (default `send_message`) as `AssistantMessage` objects.",
+        description="Whether the server should parse specific tool call arguments (default `send_message`) as `AssistantMessage` objects. Still supported for legacy agent types, but deprecated for letta_v1_agent onward.",
+        deprecated=True,
     )
     assistant_message_tool_name: str = Field(
         default=DEFAULT_MESSAGE_TOOL,
-        description="The name of the designated message tool.",
+        description="The name of the designated message tool. Still supported for legacy agent types, but deprecated for letta_v1_agent onward.",
+        deprecated=True,
     )
     assistant_message_tool_kwarg: str = Field(
         default=DEFAULT_MESSAGE_TOOL_KWARG,
-        description="The name of the message argument in the designated message tool.",
+        description="The name of the message argument in the designated message tool. Still supported for legacy agent types, but deprecated for letta_v1_agent onward.",
+        deprecated=True,
     )
 
     # filter to only return specific message types
@@ -34,6 +37,7 @@ class LettaRequest(BaseModel):
     enable_thinking: str = Field(
         default=True,
         description="If set to True, enables reasoning before responses or tool calls from the agent.",
+        deprecated=True,
     )
 
     @field_validator("messages", mode="before")

letta/schemas/letta_stop_reason.py

@@ -48,28 +48,3 @@ class LettaStopReason(BaseModel):
 
     message_type: Literal["stop_reason"] = Field("stop_reason", description="The type of the message.")
     stop_reason: StopReasonType = Field(..., description="The reason why execution stopped.")
-
-
-def create_letta_ping_schema():
-    return {
-        "properties": {
-            "message_type": {
-                "type": "string",
-                "const": "ping",
-                "title": "Message Type",
-                "description": "The type of the message.",
-                "default": "ping",
-            }
-        },
-        "type": "object",
-        "required": ["message_type"],
-        "title": "LettaPing",
-        "description": "Ping messages are a keep-alive to prevent SSE streams from timing out during long running requests.",
-    }
-
-
-class LettaPing(BaseModel):
-    message_type: Literal["ping"] = Field(
-        "ping",
-        description="The type of the message. Ping messages are a keep-alive to prevent SSE streams from timing out during long running requests.",
-    )

letta/schemas/llm_config.py

@@ -13,6 +13,8 @@ class LLMConfig(BaseModel):
     """Configuration for Language Model (LLM) connection and generation parameters."""
 
     model: str = Field(..., description="LLM model name. ")
+    display_name: Optional[str] = Field(None, description="A human-friendly display name for the model.")
+
     model_endpoint_type: Literal[
         "openai",
         "anthropic",
@@ -78,6 +80,7 @@ class LLMConfig(BaseModel):
 
     # FIXME hack to silence pydantic protected namespace warning
     model_config = ConfigDict(protected_namespaces=())
+    parallel_tool_calls: Optional[bool] = Field(False, description="If set to True, enables parallel tool calling. Defaults to False.")
 
     @model_validator(mode="before")
     @classmethod
@@ -151,7 +154,10 @@ class LLMConfig(BaseModel):
             values["put_inner_thoughts_in_kwargs"] = False
 
         if values.get("model_endpoint_type") == "anthropic" and (
-            model.startswith("claude-3-7-sonnet") or model.startswith("claude-sonnet-4") or model.startswith("claude-opus-4")
+            model.startswith("claude-3-7-sonnet")
+            or model.startswith("claude-sonnet-4")
+            or model.startswith("claude-opus-4")
+            or model.startswith("claude-haiku-4-5")
         ):
             values["put_inner_thoughts_in_kwargs"] = False
 
@@ -239,7 +245,7 @@ class LLMConfig(BaseModel):
             config.model.startswith("claude-opus-4")
             or config.model.startswith("claude-sonnet-4")
             or config.model.startswith("claude-3-7-sonnet")
-            or config.model.startswith("claude-4-5-haiku")
+            or config.model.startswith("claude-haiku-4-5")
         )
 
     @classmethod

letta/schemas/mcp.py

@@ -1,3 +1,4 @@
+import json
 from datetime import datetime
 from typing import Any, Dict, List, Optional, Union
 
@@ -13,7 +14,7 @@ from letta.functions.mcp_client.types import (
 )
 from letta.orm.mcp_oauth import OAuthSessionStatus
 from letta.schemas.letta_base import LettaBase
-from letta.schemas.secret import Secret, SecretDict
+from letta.schemas.secret import Secret
 from letta.settings import settings
 
 
@@ -31,8 +32,8 @@ class MCPServer(BaseMCPServer):
     token: Optional[str] = Field(None, description="The access token or API key for the MCP server (used for authentication)")
     custom_headers: Optional[Dict[str, str]] = Field(None, description="Custom authentication headers as key-value pairs")
 
-    token_enc: Optional[str] = Field(None, description="Encrypted token")
-    custom_headers_enc: Optional[str] = Field(None, description="Encrypted custom headers")
+    token_enc: Secret | None = Field(None, description="Encrypted token as Secret object")
+    custom_headers_enc: Secret | None = Field(None, description="Encrypted custom headers as Secret object")
 
     # stdio config
     stdio_config: Optional[StdioServerConfig] = Field(
@@ -48,55 +49,55 @@ class MCPServer(BaseMCPServer):
 
     def get_token_secret(self) -> Secret:
         """Get the token as a Secret object, preferring encrypted over plaintext."""
-        return Secret.from_db(self.token_enc, self.token)
-
-    def get_custom_headers_secret(self) -> SecretDict:
-        """Get custom headers as a SecretDict object, preferring encrypted over plaintext."""
-        return SecretDict.from_db(self.custom_headers_enc, self.custom_headers)
+        if self.token_enc is not None:
+            return self.token_enc
+        return Secret.from_db(None, self.token)
+
+    def get_custom_headers_secret(self) -> Secret:
+        """Get custom headers as a Secret object (stores JSON string), preferring encrypted over plaintext."""
+        if self.custom_headers_enc is not None:
+            return self.custom_headers_enc
+        # Fallback: convert plaintext dict to JSON string and wrap in Secret
+        if self.custom_headers is not None:
+            json_str = json.dumps(self.custom_headers)
+            return Secret.from_plaintext(json_str)
+        return Secret.from_plaintext(None)
+
+    def get_custom_headers_dict(self) -> Optional[Dict[str, str]]:
+        """Get custom headers as a plaintext dictionary."""
+        secret = self.get_custom_headers_secret()
+        json_str = secret.get_plaintext()
+        if json_str:
+            try:
+                return json.loads(json_str)
+            except (json.JSONDecodeError, TypeError):
+                return None
+        return None
 
     def set_token_secret(self, secret: Secret) -> None:
         """Set token from a Secret object, updating both encrypted and plaintext fields."""
+        self.token_enc = secret
         secret_dict = secret.to_dict()
-        self.token_enc = secret_dict["encrypted"]
         # Only set plaintext during migration phase
-        if not secret._was_encrypted:
+        if not secret.was_encrypted:
             self.token = secret_dict["plaintext"]
         else:
             self.token = None
 
-    def set_custom_headers_secret(self, secret: SecretDict) -> None:
-        """Set custom headers from a SecretDict object, updating both fields."""
+    def set_custom_headers_secret(self, secret: Secret) -> None:
+        """Set custom headers from a Secret object (containing JSON string), updating both fields."""
+        self.custom_headers_enc = secret
         secret_dict = secret.to_dict()
-        self.custom_headers_enc = secret_dict["encrypted"]
-        # Only set plaintext during migration phase
-        if not secret._was_encrypted:
-            self.custom_headers = secret_dict["plaintext"]
+        # Parse JSON string to dict for plaintext field
+        json_str = secret_dict.get("plaintext")
+        if json_str and not secret.was_encrypted:
+            try:
+                self.custom_headers = json.loads(json_str)
+            except (json.JSONDecodeError, TypeError):
+                self.custom_headers = None
         else:
             self.custom_headers = None
 
-    def model_dump(self, to_orm: bool = False, **kwargs):
-        """Override model_dump to handle encryption when saving to database."""
-        data = super().model_dump(to_orm=to_orm, **kwargs)
-
-        if to_orm and settings.encryption_key:
-            # Encrypt token if present
-            if self.token is not None:
-                token_secret = Secret.from_plaintext(self.token)
-                secret_dict = token_secret.to_dict()
-                data["token_enc"] = secret_dict["encrypted"]
-                # Keep plaintext for dual-write during migration
-                data["token"] = secret_dict["plaintext"]
-
-            # Encrypt custom headers if present
-            if self.custom_headers is not None:
-                headers_secret = SecretDict.from_plaintext(self.custom_headers)
-                secret_dict = headers_secret.to_dict()
-                data["custom_headers_enc"] = secret_dict["encrypted"]
-                # Keep plaintext for dual-write during migration
-                data["custom_headers"] = secret_dict["plaintext"]
-
-        return data
-
     def to_config(
         self,
         environment_variables: Optional[Dict[str, str]] = None,
@@ -106,8 +107,8 @@ class MCPServer(BaseMCPServer):
         token_secret = self.get_token_secret()
         token_plaintext = token_secret.get_plaintext()
 
-        headers_secret = self.get_custom_headers_secret()
-        headers_plaintext = headers_secret.get_plaintext()
+        # Get custom headers as dict
+        headers_plaintext = self.get_custom_headers_dict()
 
         if self.server_type == MCPServerType.SSE:
             config = SSEServerConfig(
@@ -147,6 +148,7 @@ class MCPServer(BaseMCPServer):
 class UpdateSSEMCPServer(LettaBase):
     """Update an SSE MCP server"""
 
+    server_name: Optional[str] = Field(None, description="The name of the MCP server")
     server_url: Optional[str] = Field(None, description="The URL of the server (MCP SSE client will connect to this URL)")
     token: Optional[str] = Field(None, description="The access token or API key for the MCP server (used for SSE authentication)")
     custom_headers: Optional[Dict[str, str]] = Field(None, description="Custom authentication headers as key-value pairs")
@@ -155,6 +157,7 @@ class UpdateSSEMCPServer(LettaBase):
 class UpdateStdioMCPServer(LettaBase):
     """Update a Stdio MCP server"""
 
+    server_name: Optional[str] = Field(None, description="The name of the MCP server")
     stdio_config: Optional[StdioServerConfig] = Field(
         None, description="The configuration for the server (MCP 'local' client will run this command)"
     )
@@ -163,6 +166,7 @@ class UpdateStdioMCPServer(LettaBase):
 class UpdateStreamableHTTPMCPServer(LettaBase):
     """Update a Streamable HTTP MCP server"""
 
+    server_name: Optional[str] = Field(None, description="The name of the MCP server")
     server_url: Optional[str] = Field(None, description="The URL path for the streamable HTTP server (e.g., 'example/mcp')")
     auth_header: Optional[str] = Field(None, description="The name of the authentication header (e.g., 'Authorization')")
     auth_token: Optional[str] = Field(None, description="The authentication token or API key value")
@@ -194,6 +198,9 @@ class MCPOAuthSession(BaseMCPOAuth):
     authorization_url: Optional[str] = Field(None, description="OAuth authorization URL")
     authorization_code: Optional[str] = Field(None, description="OAuth authorization code")
 
+    # Encrypted authorization code (for internal use)
+    authorization_code_enc: Secret | None = Field(None, description="Encrypted OAuth authorization code as Secret object")
+
     # Token data
     access_token: Optional[str] = Field(None, description="OAuth access token")
     refresh_token: Optional[str] = Field(None, description="OAuth refresh token")
@@ -202,8 +209,8 @@ class MCPOAuthSession(BaseMCPOAuth):
     scope: Optional[str] = Field(None, description="OAuth scope")
 
     # Encrypted token fields (for internal use)
-    access_token_enc: Optional[str] = Field(None, description="Encrypted OAuth access token")
-    refresh_token_enc: Optional[str] = Field(None, description="Encrypted OAuth refresh token")
+    access_token_enc: Secret | None = Field(None, description="Encrypted OAuth access token as Secret object")
+    refresh_token_enc: Secret | None = Field(None, description="Encrypted OAuth refresh token as Secret object")
 
     # Client configuration
     client_id: Optional[str] = Field(None, description="OAuth client ID")
@@ -211,7 +218,7 @@ class MCPOAuthSession(BaseMCPOAuth):
     redirect_uri: Optional[str] = Field(None, description="OAuth redirect URI")
 
     # Encrypted client secret (for internal use)
-    client_secret_enc: Optional[str] = Field(None, description="Encrypted OAuth client secret")
+    client_secret_enc: Secret | None = Field(None, description="Encrypted OAuth client secret as Secret object")
 
     # Session state
     status: OAuthSessionStatus = Field(default=OAuthSessionStatus.PENDING, description="Session status")
@@ -222,73 +229,63 @@ class MCPOAuthSession(BaseMCPOAuth):
 
     def get_access_token_secret(self) -> Secret:
         """Get the access token as a Secret object, preferring encrypted over plaintext."""
-        return Secret.from_db(self.access_token_enc, self.access_token)
+        if self.access_token_enc is not None:
+            return self.access_token_enc
+        return Secret.from_db(None, self.access_token)
 
     def get_refresh_token_secret(self) -> Secret:
         """Get the refresh token as a Secret object, preferring encrypted over plaintext."""
-        return Secret.from_db(self.refresh_token_enc, self.refresh_token)
+        if self.refresh_token_enc is not None:
+            return self.refresh_token_enc
+        return Secret.from_db(None, self.refresh_token)
 
     def get_client_secret_secret(self) -> Secret:
         """Get the client secret as a Secret object, preferring encrypted over plaintext."""
-        return Secret.from_db(self.client_secret_enc, self.client_secret)
+        if self.client_secret_enc is not None:
+            return self.client_secret_enc
+        return Secret.from_db(None, self.client_secret)
+
+    def get_authorization_code_secret(self) -> Secret:
+        """Get the authorization code as a Secret object, preferring encrypted over plaintext."""
+        if self.authorization_code_enc is not None:
+            return self.authorization_code_enc
+        return Secret.from_db(None, self.authorization_code)
 
     def set_access_token_secret(self, secret: Secret) -> None:
         """Set access token from a Secret object."""
+        self.access_token_enc = secret
         secret_dict = secret.to_dict()
-        self.access_token_enc = secret_dict["encrypted"]
-        if not secret._was_encrypted:
+        if not secret.was_encrypted:
             self.access_token = secret_dict["plaintext"]
         else:
             self.access_token = None
 
     def set_refresh_token_secret(self, secret: Secret) -> None:
         """Set refresh token from a Secret object."""
+        self.refresh_token_enc = secret
         secret_dict = secret.to_dict()
-        self.refresh_token_enc = secret_dict["encrypted"]
-        if not secret._was_encrypted:
+        if not secret.was_encrypted:
             self.refresh_token = secret_dict["plaintext"]
         else:
             self.refresh_token = None
 
     def set_client_secret_secret(self, secret: Secret) -> None:
         """Set client secret from a Secret object."""
+        self.client_secret_enc = secret
         secret_dict = secret.to_dict()
-        self.client_secret_enc = secret_dict["encrypted"]
-        if not secret._was_encrypted:
+        if not secret.was_encrypted:
             self.client_secret = secret_dict["plaintext"]
         else:
             self.client_secret = None
 
-    def model_dump(self, to_orm: bool = False, **kwargs):
-        """Override model_dump to handle encryption when saving to database."""
-        data = super().model_dump(to_orm=to_orm, **kwargs)
-
-        if to_orm and settings.encryption_key:
-            # Encrypt access token if present
-            if self.access_token is not None:
-                token_secret = Secret.from_plaintext(self.access_token)
-                secret_dict = token_secret.to_dict()
-                data["access_token_enc"] = secret_dict["encrypted"]
-                # Keep plaintext for dual-write during migration
-                data["access_token"] = secret_dict["plaintext"]
-
-            # Encrypt refresh token if present
-            if self.refresh_token is not None:
-                token_secret = Secret.from_plaintext(self.refresh_token)
-                secret_dict = token_secret.to_dict()
-                data["refresh_token_enc"] = secret_dict["encrypted"]
-                # Keep plaintext for dual-write during migration
-                data["refresh_token"] = secret_dict["plaintext"]
-
-            # Encrypt client secret if present
-            if self.client_secret is not None:
-                secret = Secret.from_plaintext(self.client_secret)
-                secret_dict = secret.to_dict()
-                data["client_secret_enc"] = secret_dict["encrypted"]
-                # Keep plaintext for dual-write during migration
-                data["client_secret"] = secret_dict["plaintext"]
-
-        return data
+    def set_authorization_code_secret(self, secret: Secret) -> None:
+        """Set authorization code from a Secret object."""
+        self.authorization_code_enc = secret
+        secret_dict = secret.to_dict()
+        if not secret.was_encrypted:
+            self.authorization_code = secret_dict["plaintext"]
+        else:
+            self.authorization_code = None
 
 
 class MCPOAuthSessionCreate(BaseMCPOAuth):