letta-nightly 0.11.7.dev20250909104137__py3-none-any.whl → 0.11.7.dev20250910104051__py3-none-any.whl

letta/agents/voice_agent.py

@@ -494,7 +494,8 @@ class VoiceAgent(BaseAgent):
             start_date=start_date,
             end_date=end_date,
         )
-        formatted_archival_results = [{"timestamp": str(result.created_at), "content": result.text} for result in archival_results]
+        # Extract passages from tuples and format
+        formatted_archival_results = [{"timestamp": str(passage.created_at), "content": passage.text} for passage, _, _ in archival_results]
         response = {
             "archival_search_results": formatted_archival_results,
         }

letta/constants.py

@@ -173,7 +173,7 @@ CONVERSATION_SEARCH_TOOL_NAME = "conversation_search"
 PRE_EXECUTION_MESSAGE_ARG = "pre_exec_msg"
 
 REQUEST_HEARTBEAT_PARAM = "request_heartbeat"
-REQUEST_HEARTBEAT_DESCRIPTION = "Request an immediate heartbeat after function execution. Set to `True` if you want to send a follow-up message or run a follow-up function."
+REQUEST_HEARTBEAT_DESCRIPTION = "Request an immediate heartbeat after function execution. You MUST set this value to `True` if you want to send a follow-up message or run a follow-up tool call (chain multiple tools together). If set to `False` (the default), then the chain of execution will end immediately after this function call."
 
 
 # Structured output models

letta/errors.py

@@ -18,6 +18,7 @@ class ErrorCode(Enum):
     CONTEXT_WINDOW_EXCEEDED = "CONTEXT_WINDOW_EXCEEDED"
     RATE_LIMIT_EXCEEDED = "RATE_LIMIT_EXCEEDED"
     TIMEOUT = "TIMEOUT"
+    CONFLICT = "CONFLICT"
 
 
 class LettaError(Exception):
@@ -40,6 +41,17 @@ class LettaError(Exception):
         return f"{self.__class__.__name__}(message='{self.message}', code='{self.code}', details={self.details})"
 
 
+class PendingApprovalError(LettaError):
+    """Error raised when attempting an operation while agent is waiting for tool approval."""
+
+    def __init__(self, pending_request_id: Optional[str] = None):
+        self.pending_request_id = pending_request_id
+        message = "Cannot send a new message: The agent is waiting for approval on a tool call. Please approve or deny the pending request before continuing."
+        code = ErrorCode.CONFLICT
+        details = {"error_code": "PENDING_APPROVAL", "pending_request_id": pending_request_id}
+        super().__init__(message=message, code=code, details=details)
+
+
 class LettaToolCreateError(LettaError):
     """Error raised when a tool cannot be created."""
 

letta/functions/function_sets/base.py

@@ -35,8 +35,8 @@ def conversation_search(
         query (str): String to search for using both text matching and semantic similarity.
         roles (Optional[List[Literal["assistant", "user", "tool"]]]): Optional list of message roles to filter by.
         limit (Optional[int]): Maximum number of results to return. Uses system default if not specified.
-        start_date (Optional[str]): Filter results to messages created after this date. ISO 8601 format: "YYYY-MM-DD" or "YYYY-MM-DDTHH:MM". Examples: "2024-01-15", "2024-01-15T14:30".
-        end_date (Optional[str]): Filter results to messages created before this date. ISO 8601 format: "YYYY-MM-DD" or "YYYY-MM-DDTHH:MM". Examples: "2024-01-20", "2024-01-20T17:00".
+        start_date (Optional[str]): Filter results to messages created on or after this date (INCLUSIVE). When using date-only format (e.g., "2024-01-15"), includes messages starting from 00:00:00 of that day. ISO 8601 format: "YYYY-MM-DD" or "YYYY-MM-DDTHH:MM". Examples: "2024-01-15" (from start of Jan 15), "2024-01-15T14:30" (from 2:30 PM on Jan 15).
+        end_date (Optional[str]): Filter results to messages created on or before this date (INCLUSIVE). When using date-only format (e.g., "2024-01-20"), includes all messages from that entire day. ISO 8601 format: "YYYY-MM-DD" or "YYYY-MM-DDTHH:MM". Examples: "2024-01-20" (includes all of Jan 20), "2024-01-20T17:00" (up to 5 PM on Jan 20).
 
     Examples:
         # Search all messages
@@ -45,8 +45,17 @@ def conversation_search(
         # Search only assistant messages
         conversation_search(query="error handling", roles=["assistant"])
 
-        # Search with date range
+        # Search with date range (inclusive of both dates)
         conversation_search(query="meetings", start_date="2024-01-15", end_date="2024-01-20")
+        # This includes all messages from Jan 15 00:00:00 through Jan 20 23:59:59
+
+        # Search messages from a specific day (inclusive)
+        conversation_search(query="bug reports", start_date="2024-09-04", end_date="2024-09-04")
+        # This includes ALL messages from September 4, 2024
+
+        # Search with specific time boundaries
+        conversation_search(query="deployment", start_date="2024-01-15T09:00", end_date="2024-01-15T17:30")
+        # This includes messages from 9 AM to 5:30 PM on Jan 15
 
         # Search with limit
         conversation_search(query="debugging", limit=10)
@@ -115,18 +124,24 @@ async def archival_memory_search(
         tags (Optional[list[str]]): Optional list of tags to filter search results. Only passages with these tags will be returned.
         tag_match_mode (Literal["any", "all"]): How to match tags - "any" to match passages with any of the tags, "all" to match only passages with all tags. Defaults to "any".
         top_k (Optional[int]): Maximum number of results to return. Uses system default if not specified.
-        start_datetime (Optional[str]): Filter results to passages created after this datetime. ISO 8601 format: "YYYY-MM-DD" or "YYYY-MM-DDTHH:MM". Examples: "2024-01-15", "2024-01-15T14:30".
-        end_datetime (Optional[str]): Filter results to passages created before this datetime. ISO 8601 format: "YYYY-MM-DD" or "YYYY-MM-DDTHH:MM". Examples: "2024-01-20", "2024-01-20T17:00".
+        start_datetime (Optional[str]): Filter results to passages created on or after this datetime (INCLUSIVE). When using date-only format (e.g., "2024-01-15"), includes passages starting from 00:00:00 of that day. ISO 8601 format: "YYYY-MM-DD" or "YYYY-MM-DDTHH:MM". Examples: "2024-01-15" (from start of Jan 15), "2024-01-15T14:30" (from 2:30 PM on Jan 15).
+        end_datetime (Optional[str]): Filter results to passages created on or before this datetime (INCLUSIVE). When using date-only format (e.g., "2024-01-20"), includes all passages from that entire day. ISO 8601 format: "YYYY-MM-DD" or "YYYY-MM-DDTHH:MM". Examples: "2024-01-20" (includes all of Jan 20), "2024-01-20T17:00" (up to 5 PM on Jan 20).
 
     Examples:
         # Search all passages
         archival_memory_search(query="project updates")
 
-        # Search with date range (full days)
+        # Search with date range (inclusive of both dates)
         archival_memory_search(query="meetings", start_datetime="2024-01-15", end_datetime="2024-01-20")
+        # This includes all passages from Jan 15 00:00:00 through Jan 20 23:59:59
+
+        # Search passages from a specific day (inclusive)
+        archival_memory_search(query="bug reports", start_datetime="2024-09-04", end_datetime="2024-09-04")
+        # This includes ALL passages from September 4, 2024
 
         # Search with specific time range
         archival_memory_search(query="error logs", start_datetime="2024-01-15T09:30", end_datetime="2024-01-15T17:30")
+        # This includes passages from 9:30 AM to 5:30 PM on Jan 15
 
         # Search from a specific point in time onwards
         archival_memory_search(query="customer feedback", start_datetime="2024-01-15T14:00")
@@ -208,6 +223,25 @@ def memory_replace(agent_state: "AgentState", label: str, old_str: str, new_str:
         old_str (str): The text to replace (must match exactly, including whitespace and indentation).
         new_str (str): The new text to insert in place of the old text. Do not include line number prefixes.
 
+    Examples:
+        # Update a block containing information about the user
+        memory_replace(label="human", old_str="Their name is Alice", new_str="Their name is Bob")
+
+        # Update a block containing a todo list
+        memory_replace(label="todos", old_str="- [ ] Step 5: Search the web", new_str="- [x] Step 5: Search the web")
+
+        # Pass an empty string to
+        memory_replace(label="human", old_str="Their name is Alice", new_str="")
+
+        # Bad example - do NOT add (view-only) line numbers to the args
+        memory_replace(label="human", old_str="Line 1: Their name is Alice", new_str="Line 1: Their name is Bob")
+
+        # Bad example - do NOT include the number number warning either
+        memory_replace(label="human", old_str="# NOTE: Line numbers shown below are to help during editing. Do NOT include line number prefixes in your memory edit tool calls.\\nLine 1: Their name is Alice", new_str="Line 1: Their name is Bob")
+
+        # Good example - no line numbers or line number warning (they are view-only), just the text
+        memory_replace(label="human", old_str="Their name is Alice", new_str="Their name is Bob")
+
     Returns:
         str: The success message
     """
@@ -248,11 +282,11 @@ def memory_replace(agent_state: "AgentState", label: str, old_str: str, new_str:
     agent_state.memory.update_block_value(label=label, value=new_value)
 
     # Create a snippet of the edited section
-    SNIPPET_LINES = 3
-    replacement_line = current_value.split(old_str)[0].count("\n")
-    start_line = max(0, replacement_line - SNIPPET_LINES)
-    end_line = replacement_line + SNIPPET_LINES + new_str.count("\n")
-    snippet = "\n".join(new_value.split("\n")[start_line : end_line + 1])
+    # SNIPPET_LINES = 3
+    # replacement_line = current_value.split(old_str)[0].count("\n")
+    # start_line = max(0, replacement_line - SNIPPET_LINES)
+    # end_line = replacement_line + SNIPPET_LINES + new_str.count("\n")
+    # snippet = "\n".join(new_value.split("\n")[start_line : end_line + 1])
 
     # Prepare the success message
     success_msg = f"The core memory block with label `{label}` has been edited. "
@@ -275,6 +309,13 @@ def memory_insert(agent_state: "AgentState", label: str, new_str: str, insert_li
         new_str (str): The text to insert. Do not include line number prefixes.
         insert_line (int): The line number after which to insert the text (0 for beginning of file). Defaults to -1 (end of the file).
 
+    Examples:
+        # Update a block containing information about the user (append to the end of the block)
+        memory_insert(label="customer", new_str="The customer's ticket number is 12345")
+
+        # Update a block containing information about the user (insert at the beginning of the block)
+        memory_insert(label="customer", new_str="The customer's ticket number is 12345", insert_line=0)
+
     Returns:
         Optional[str]: None is always returned as this function does not produce a response.
     """
@@ -313,7 +354,7 @@ def memory_insert(agent_state: "AgentState", label: str, new_str: str, insert_li
 
     # Collate into the new value to update
     new_value = "\n".join(new_value_lines)
-    snippet = "\n".join(snippet_lines)
+    # snippet = "\n".join(snippet_lines)
 
     # Write into the block
     agent_state.memory.update_block_value(label=label, value=new_value)

letta/functions/schema_generator.py

@@ -622,7 +622,7 @@ def generate_tool_schema_for_mcp(
                             format_value = option["format"]
                 if types:
                     # Deduplicate types using set
-                    field_props["type"] = list(set(types))
+                    field_props["type"] = list(dict.fromkeys(types))
                     # Only add format if the field is not optional (doesn't have null type)
                     if format_value and len(field_props["type"]) == 1 and "null" not in field_props["type"]:
                         field_props["format"] = format_value

letta/groups/sleeptime_multi_agent_v3.py

@@ -0,0 +1,231 @@
+import asyncio
+from collections.abc import AsyncGenerator
+from datetime import datetime, timezone
+
+from letta.agents.letta_agent_v2 import LettaAgentV2
+from letta.constants import DEFAULT_MAX_STEPS
+from letta.groups.helpers import stringify_message
+from letta.otel.tracing import trace_method
+from letta.schemas.agent import AgentState
+from letta.schemas.enums import JobStatus
+from letta.schemas.group import Group, ManagerType
+from letta.schemas.job import JobUpdate
+from letta.schemas.letta_message import MessageType
+from letta.schemas.letta_message_content import TextContent
+from letta.schemas.letta_response import LettaResponse
+from letta.schemas.message import Message, MessageCreate
+from letta.schemas.run import Run
+from letta.schemas.user import User
+from letta.services.group_manager import GroupManager
+
+
+class SleeptimeMultiAgentV3(LettaAgentV2):
+    def __init__(
+        self,
+        agent_state: AgentState,
+        actor: User,
+        group: Group,
+    ):
+        super().__init__(agent_state, actor)
+        assert group.manager_type == ManagerType.sleeptime, f"Expected group type to be 'sleeptime', got {group.manager_type}"
+        self.group = group
+        self.run_ids = []
+
+        # Additional manager classes
+        self.group_manager = GroupManager()
+
+    @trace_method
+    async def step(
+        self,
+        input_messages: list[MessageCreate],
+        max_steps: int = DEFAULT_MAX_STEPS,
+        run_id: str | None = None,
+        use_assistant_message: bool = False,
+        include_return_message_types: list[MessageType] | None = None,
+        request_start_timestamp_ns: int | None = None,
+    ) -> LettaResponse:
+        self.run_ids = []
+
+        for i in range(len(input_messages)):
+            input_messages[i].group_id = self.group.id
+
+        response = await super().step(
+            input_messages=input_messages,
+            max_steps=max_steps,
+            run_id=run_id,
+            use_assistant_message=use_assistant_message,
+            include_return_message_types=include_return_message_types,
+            request_start_timestamp_ns=request_start_timestamp_ns,
+        )
+
+        await self.run_sleeptime_agents(use_assistant_message=use_assistant_message)
+
+        response.usage.run_ids = self.run_ids
+        return response
+
+    @trace_method
+    async def stream(
+        self,
+        input_messages: list[MessageCreate],
+        max_steps: int = DEFAULT_MAX_STEPS,
+        stream_tokens: bool = True,
+        run_id: str | None = None,
+        use_assistant_message: bool = True,
+        request_start_timestamp_ns: int | None = None,
+        include_return_message_types: list[MessageType] | None = None,
+    ) -> AsyncGenerator[str, None]:
+        self.run_ids = []
+
+        for i in range(len(input_messages)):
+            input_messages[i].group_id = self.group.id
+
+        # Perform foreground agent step
+        async for chunk in super().stream(
+            input_messages=input_messages,
+            max_steps=max_steps,
+            stream_tokens=stream_tokens,
+            run_id=run_id,
+            use_assistant_message=use_assistant_message,
+            include_return_message_types=include_return_message_types,
+            request_start_timestamp_ns=request_start_timestamp_ns,
+        ):
+            yield chunk
+
+        await self.run_sleeptime_agents(use_assistant_message=use_assistant_message)
+
+    @trace_method
+    async def run_sleeptime_agents(self, use_assistant_message: bool = True):
+        # Get response messages
+        last_response_messages = self.response_messages
+
+        # Update turns counter
+        turns_counter = None
+        if self.group.sleeptime_agent_frequency is not None and self.group.sleeptime_agent_frequency > 0:
+            turns_counter = await self.group_manager.bump_turns_counter_async(group_id=self.group.id, actor=self.actor)
+
+        # Perform participant steps
+        if self.group.sleeptime_agent_frequency is None or (
+            turns_counter is not None and turns_counter % self.group.sleeptime_agent_frequency == 0
+        ):
+            last_processed_message_id = await self.group_manager.get_last_processed_message_id_and_update_async(
+                group_id=self.group.id, last_processed_message_id=last_response_messages[-1].id, actor=self.actor
+            )
+            for sleeptime_agent_id in self.group.agent_ids:
+                try:
+                    sleeptime_run_id = await self._issue_background_task(
+                        sleeptime_agent_id,
+                        last_response_messages,
+                        last_processed_message_id,
+                        use_assistant_message,
+                    )
+                    self.run_ids.append(sleeptime_run_id)
+                except Exception as e:
+                    # Individual task failures
+                    print(f"Sleeptime agent processing failed: {e!s}")
+                    raise e
+
+    @trace_method
+    async def _issue_background_task(
+        self,
+        sleeptime_agent_id: str,
+        response_messages: list[Message],
+        last_processed_message_id: str,
+        use_assistant_message: bool = True,
+    ) -> str:
+        run = Run(
+            user_id=self.actor.id,
+            status=JobStatus.created,
+            metadata={
+                "job_type": "sleeptime_agent_send_message_async",  # is this right?
+                "agent_id": sleeptime_agent_id,
+            },
+        )
+        run = await self.job_manager.create_job_async(pydantic_job=run, actor=self.actor)
+
+        asyncio.create_task(
+            self._participant_agent_step(
+                foreground_agent_id=self.agent_state.id,
+                sleeptime_agent_id=sleeptime_agent_id,
+                response_messages=response_messages,
+                last_processed_message_id=last_processed_message_id,
+                run_id=run.id,
+                use_assistant_message=use_assistant_message,
+            )
+        )
+        return run.id
+
+    @trace_method
+    async def _participant_agent_step(
+        self,
+        foreground_agent_id: str,
+        sleeptime_agent_id: str,
+        response_messages: list[Message],
+        last_processed_message_id: str,
+        run_id: str,
+        use_assistant_message: bool = True,
+    ) -> LettaResponse:
+        try:
+            # Update job status
+            job_update = JobUpdate(status=JobStatus.running)
+            await self.job_manager.update_job_by_id_async(job_id=run_id, job_update=job_update, actor=self.actor)
+
+            # Create conversation transcript
+            prior_messages = []
+            if self.group.sleeptime_agent_frequency:
+                try:
+                    prior_messages = await self.message_manager.list_messages_for_agent_async(
+                        agent_id=foreground_agent_id,
+                        actor=self.actor,
+                        after=last_processed_message_id,
+                        before=response_messages[0].id,
+                    )
+                except Exception:
+                    pass  # continue with just latest messages
+
+            transcript_summary = [stringify_message(message) for message in prior_messages + response_messages]
+            transcript_summary = [summary for summary in transcript_summary if summary is not None]
+            message_text = "\n".join(transcript_summary)
+
+            sleeptime_agent_messages = [
+                MessageCreate(
+                    role="user",
+                    content=[TextContent(text=message_text)],
+                    id=Message.generate_id(),
+                    agent_id=sleeptime_agent_id,
+                    group_id=self.group.id,
+                )
+            ]
+
+            # Load sleeptime agent
+            sleeptime_agent_state = await self.agent_manager.get_agent_by_id_async(agent_id=sleeptime_agent_id, actor=self.actor)
+            sleeptime_agent = LettaAgentV2(
+                agent_state=sleeptime_agent_state,
+                actor=self.actor,
+            )
+
+            # Perform sleeptime agent step
+            result = await sleeptime_agent.step(
+                input_messages=sleeptime_agent_messages,
+                run_id=run_id,
+                use_assistant_message=use_assistant_message,
+            )
+
+            # Update job status
+            job_update = JobUpdate(
+                status=JobStatus.completed,
+                completed_at=datetime.now(timezone.utc).replace(tzinfo=None),
+                metadata={
+                    "result": result.model_dump(mode="json"),
+                    "agent_id": sleeptime_agent_state.id,
+                },
+            )
+            await self.job_manager.update_job_by_id_async(job_id=run_id, job_update=job_update, actor=self.actor)
+            return result
+        except Exception as e:
+            job_update = JobUpdate(
+                status=JobStatus.failed,
+                completed_at=datetime.now(timezone.utc).replace(tzinfo=None),
+                metadata={"error": str(e)},
+            )
+            await self.job_manager.update_job_by_id_async(job_id=run_id, job_update=job_update, actor=self.actor)
+            raise

letta/helpers/tool_rule_solver.py

@@ -131,6 +131,10 @@ class ToolRulesSolver(BaseModel):
         """Check if all required-before-exit tools have been called."""
         return len(self.get_uncalled_required_tools(available_tools=available_tools)) == 0
 
+    def get_requires_approval_tools(self, available_tools: set[ToolName]) -> list[ToolName]:
+        """Get the list of tools that require approval."""
+        return [rule.tool_name for rule in self.requires_approval_tool_rules]
+
     def get_uncalled_required_tools(self, available_tools: set[ToolName]) -> list[str]:
         """Get the list of required-before-exit tools that have not been called yet."""
         if not self.required_before_exit_tool_rules: