letta-nightly 0.11.4.dev20250826104242__py3-none-any.whl → 0.11.6.dev20250827050912__py3-none-any.whl

letta/prompts/prompt_generator.py

@@ -0,0 +1,190 @@
+from datetime import datetime
+from typing import List, Literal, Optional
+
+from letta.constants import IN_CONTEXT_MEMORY_KEYWORD
+from letta.helpers import ToolRulesSolver
+from letta.helpers.datetime_helpers import format_datetime, get_local_time_fast
+from letta.otel.tracing import trace_method
+from letta.schemas.memory import Memory
+
+
+class PromptGenerator:
+
+    # TODO: This code is kind of wonky and deserves a rewrite
+    @trace_method
+    @staticmethod
+    def compile_memory_metadata_block(
+        memory_edit_timestamp: datetime,
+        timezone: str,
+        previous_message_count: int = 0,
+        archival_memory_size: Optional[int] = 0,
+    ) -> str:
+        """
+        Generate a memory metadata block for the agent's system prompt.
+
+        This creates a structured metadata section that informs the agent about
+        the current state of its memory systems, including timing information
+        and memory counts. This helps the agent understand what information
+        is available through its tools.
+
+        Args:
+            memory_edit_timestamp: When memory blocks were last modified
+            timezone: The timezone to use for formatting timestamps (e.g., 'America/Los_Angeles')
+            previous_message_count: Number of messages in recall memory (conversation history)
+            archival_memory_size: Number of items in archival memory (long-term storage)
+
+        Returns:
+            A formatted string containing the memory metadata block with XML-style tags
+
+        Example Output:
+            <memory_metadata>
+            - The current time is: 2024-01-15 10:30 AM PST
+            - Memory blocks were last modified: 2024-01-15 09:00 AM PST
+            - 42 previous messages between you and the user are stored in recall memory (use tools to access them)
+            - 156 total memories you created are stored in archival memory (use tools to access them)
+            </memory_metadata>
+        """
+        # Put the timestamp in the local timezone (mimicking get_local_time())
+        timestamp_str = format_datetime(memory_edit_timestamp, timezone)
+
+        # Create a metadata block of info so the agent knows about the metadata of out-of-context memories
+        metadata_lines = [
+            "<memory_metadata>",
+            f"- The current time is: {get_local_time_fast(timezone)}",
+            f"- Memory blocks were last modified: {timestamp_str}",
+            f"- {previous_message_count} previous messages between you and the user are stored in recall memory (use tools to access them)",
+        ]
+
+        # Only include archival memory line if there are archival memories
+        if archival_memory_size is not None and archival_memory_size > 0:
+            metadata_lines.append(
+                f"- {archival_memory_size} total memories you created are stored in archival memory (use tools to access them)"
+            )
+
+        metadata_lines.append("</memory_metadata>")
+        memory_metadata_block = "\n".join(metadata_lines)
+        return memory_metadata_block
+
+    @staticmethod
+    def safe_format(template: str, variables: dict) -> str:
+        """
+        Safely formats a template string, preserving empty {} and {unknown_vars}
+        while substituting known variables.
+
+        If we simply use {} in format_map, it'll be treated as a positional field
+        """
+        # First escape any empty {} by doubling them
+        escaped = template.replace("{}", "{{}}")
+
+        # Now use format_map with our custom mapping
+        return escaped.format_map(PreserveMapping(variables))
+
+    @trace_method
+    @staticmethod
+    def get_system_message_from_compiled_memory(
+        system_prompt: str,
+        memory_with_sources: str,
+        in_context_memory_last_edit: datetime,  # TODO move this inside of BaseMemory?
+        timezone: str,
+        user_defined_variables: Optional[dict] = None,
+        append_icm_if_missing: bool = True,
+        template_format: Literal["f-string", "mustache", "jinja2"] = "f-string",
+        previous_message_count: int = 0,
+        archival_memory_size: int = 0,
+    ) -> str:
+        """Prepare the final/full system message that will be fed into the LLM API
+
+        The base system message may be templated, in which case we need to render the variables.
+
+        The following are reserved variables:
+        - CORE_MEMORY: the in-context memory of the LLM
+        """
+        if user_defined_variables is not None:
+            # TODO eventually support the user defining their own variables to inject
+            raise NotImplementedError
+        else:
+            variables = {}
+
+        # Add the protected memory variable
+        if IN_CONTEXT_MEMORY_KEYWORD in variables:
+            raise ValueError(f"Found protected variable '{IN_CONTEXT_MEMORY_KEYWORD}' in user-defined vars: {str(user_defined_variables)}")
+        else:
+            # TODO should this all put into the memory.__repr__ function?
+            memory_metadata_string = PromptGenerator.compile_memory_metadata_block(
+                memory_edit_timestamp=in_context_memory_last_edit,
+                previous_message_count=previous_message_count,
+                archival_memory_size=archival_memory_size,
+                timezone=timezone,
+            )
+
+            full_memory_string = memory_with_sources + "\n\n" + memory_metadata_string
+
+            # Add to the variables list to inject
+            variables[IN_CONTEXT_MEMORY_KEYWORD] = full_memory_string
+
+        if template_format == "f-string":
+            memory_variable_string = "{" + IN_CONTEXT_MEMORY_KEYWORD + "}"
+
+            # Catch the special case where the system prompt is unformatted
+            if append_icm_if_missing:
+                if memory_variable_string not in system_prompt:
+                    # In this case, append it to the end to make sure memory is still injected
+                    # warnings.warn(f"{IN_CONTEXT_MEMORY_KEYWORD} variable was missing from system prompt, appending instead")
+                    system_prompt += "\n\n" + memory_variable_string
+
+            # render the variables using the built-in templater
+            try:
+                if user_defined_variables:
+                    formatted_prompt = PromptGenerator.safe_format(system_prompt, variables)
+                else:
+                    formatted_prompt = system_prompt.replace(memory_variable_string, full_memory_string)
+            except Exception as e:
+                raise ValueError(f"Failed to format system prompt - {str(e)}. System prompt value:\n{system_prompt}")
+
+        else:
+            # TODO support for mustache and jinja2
+            raise NotImplementedError(template_format)
+
+        return formatted_prompt
+
+    @trace_method
+    @staticmethod
+    async def compile_system_message_async(
+        system_prompt: str,
+        in_context_memory: Memory,
+        in_context_memory_last_edit: datetime,  # TODO move this inside of BaseMemory?
+        timezone: str,
+        user_defined_variables: Optional[dict] = None,
+        append_icm_if_missing: bool = True,
+        template_format: Literal["f-string", "mustache", "jinja2"] = "f-string",
+        previous_message_count: int = 0,
+        archival_memory_size: int = 0,
+        tool_rules_solver: Optional[ToolRulesSolver] = None,
+        sources: Optional[List] = None,
+        max_files_open: Optional[int] = None,
+    ) -> str:
+        tool_constraint_block = None
+        if tool_rules_solver is not None:
+            tool_constraint_block = tool_rules_solver.compile_tool_rule_prompts()
+
+        if user_defined_variables is not None:
+            # TODO eventually support the user defining their own variables to inject
+            raise NotImplementedError
+        else:
+            pass
+
+        memory_with_sources = await in_context_memory.compile_in_thread_async(
+            tool_usage_rules=tool_constraint_block, sources=sources, max_files_open=max_files_open
+        )
+
+        return PromptGenerator.get_system_message_from_compiled_memory(
+            system_prompt=system_prompt,
+            memory_with_sources=memory_with_sources,
+            in_context_memory_last_edit=in_context_memory_last_edit,
+            timezone=timezone,
+            user_defined_variables=user_defined_variables,
+            append_icm_if_missing=append_icm_if_missing,
+            template_format=template_format,
+            previous_message_count=previous_message_count,
+            archival_memory_size=archival_memory_size,
+        )

letta/schemas/agent_file.py

@@ -1,15 +1,17 @@
 from datetime import datetime
 from typing import Any, Dict, List, Optional
 
+from openai.types.chat.chat_completion_message_tool_call import ChatCompletionMessageToolCall as OpenAIToolCall
 from pydantic import BaseModel, Field
 
+from letta.helpers.datetime_helpers import get_utc_time
 from letta.schemas.agent import AgentState, CreateAgent
 from letta.schemas.block import Block, CreateBlock
 from letta.schemas.enums import MessageRole
 from letta.schemas.file import FileAgent, FileAgentBase, FileMetadata, FileMetadataBase
 from letta.schemas.group import Group, GroupCreate
 from letta.schemas.mcp import MCPServer
-from letta.schemas.message import Message, MessageCreate
+from letta.schemas.message import Message, MessageCreate, ToolReturn
 from letta.schemas.source import Source, SourceCreate
 from letta.schemas.tool import Tool
 from letta.schemas.user import User
@@ -46,6 +48,15 @@ class MessageSchema(MessageCreate):
     role: MessageRole = Field(..., description="The role of the participant.")
     model: Optional[str] = Field(None, description="The model used to make the function call")
     agent_id: Optional[str] = Field(None, description="The unique identifier of the agent")
+    tool_calls: Optional[List[OpenAIToolCall]] = Field(
+        default=None, description="The list of tool calls requested. Only applicable for role assistant."
+    )
+    tool_call_id: Optional[str] = Field(default=None, description="The ID of the tool call. Only applicable for role tool.")
+    tool_returns: Optional[List[ToolReturn]] = Field(default=None, description="Tool execution return information for prior tool calls")
+    created_at: datetime = Field(default_factory=get_utc_time, description="The timestamp when the object was created.")
+
+    # TODO: Should we also duplicate the steps here?
+    # TODO: What about tool_return?
 
     @classmethod
     def from_message(cls, message: Message) -> "MessageSchema":
@@ -64,6 +75,10 @@ class MessageSchema(MessageCreate):
             group_id=message.group_id,
             model=message.model,
             agent_id=message.agent_id,
+            tool_calls=message.tool_calls,
+            tool_call_id=message.tool_call_id,
+            tool_returns=message.tool_returns,
+            created_at=message.created_at,
         )
 
 
@@ -114,7 +129,7 @@ class AgentSchema(CreateAgent):
             memory_blocks=[],  # TODO: Convert from agent_state.memory if needed
             tools=[],
             tool_ids=[tool.id for tool in agent_state.tools] if agent_state.tools else [],
-            source_ids=[],  # [source.id for source in agent_state.sources] if agent_state.sources else [],
+            source_ids=[source.id for source in agent_state.sources] if agent_state.sources else [],
             block_ids=[block.id for block in agent_state.memory.blocks],
             tool_rules=agent_state.tool_rules,
             tags=agent_state.tags,

letta/schemas/file.py

@@ -1,6 +1,6 @@
 from datetime import datetime
 from enum import Enum
-from typing import Optional
+from typing import List, Optional
 
 from pydantic import Field
 
@@ -108,3 +108,26 @@ class FileAgent(FileAgentBase):
         default_factory=datetime.utcnow,
         description="Row last-update timestamp (UTC).",
     )
+
+
+class AgentFileAttachment(LettaBase):
+    """Response model for agent file attachments showing file status in agent context"""
+
+    id: str = Field(..., description="Unique identifier of the file-agent relationship")
+    file_id: str = Field(..., description="Unique identifier of the file")
+    file_name: str = Field(..., description="Name of the file")
+    folder_id: str = Field(..., description="Unique identifier of the folder/source")
+    folder_name: str = Field(..., description="Name of the folder/source")
+    is_open: bool = Field(..., description="Whether the file is currently open in the agent's context")
+    last_accessed_at: Optional[datetime] = Field(None, description="Timestamp of last access by the agent")
+    visible_content: Optional[str] = Field(None, description="Portion of the file visible to the agent if open")
+    start_line: Optional[int] = Field(None, description="Starting line number if file was opened with line range")
+    end_line: Optional[int] = Field(None, description="Ending line number if file was opened with line range")
+
+
+class PaginatedAgentFiles(LettaBase):
+    """Paginated response for agent files"""
+
+    files: List[AgentFileAttachment] = Field(..., description="List of file attachments for the agent")
+    next_cursor: Optional[str] = Field(None, description="Cursor for fetching the next page (file-agent relationship ID)")
+    has_more: bool = Field(..., description="Whether more results exist after this page")

letta/schemas/job.py

@@ -4,6 +4,7 @@ from typing import List, Optional
 from pydantic import BaseModel, ConfigDict, Field
 
 from letta.constants import DEFAULT_MESSAGE_TOOL, DEFAULT_MESSAGE_TOOL_KWARG
+from letta.helpers.datetime_helpers import get_utc_time
 from letta.schemas.enums import JobStatus, JobType
 from letta.schemas.letta_base import OrmMetadataBase
 from letta.schemas.letta_message import MessageType
@@ -12,6 +13,7 @@ from letta.schemas.letta_message import MessageType
 class JobBase(OrmMetadataBase):
     __id_prefix__ = "job"
     status: JobStatus = Field(default=JobStatus.created, description="The status of the job.")
+    created_at: datetime = Field(default_factory=get_utc_time, description="The unix timestamp of when the job was created.")
     completed_at: Optional[datetime] = Field(None, description="The unix timestamp of when the job was completed.")
     metadata: Optional[dict] = Field(None, validation_alias="metadata_", description="The metadata of the job.")
     job_type: JobType = Field(default=JobType.JOB, description="The type of the job.")

letta/schemas/letta_message.py

@@ -52,6 +52,8 @@ class LettaMessage(BaseModel):
     sender_id: str | None = None
     step_id: str | None = None
     is_err: bool | None = None
+    seq_id: int | None = None
+    run_id: str | None = None
 
     @field_serializer("date")
     def serialize_datetime(self, dt: datetime, _info):

letta/schemas/letta_request.py

@@ -46,6 +46,10 @@ class LettaStreamingRequest(LettaRequest):
         default=False,
         description="Whether to include periodic keepalive ping messages in the stream to prevent connection timeouts.",
     )
+    background: bool = Field(
+        default=False,
+        description="Whether to process the request in the background.",
+    )
 
 
 class LettaAsyncRequest(LettaRequest):
@@ -66,3 +70,21 @@ class CreateBatch(BaseModel):
         "'status' is the final batch status (e.g., 'completed', 'failed'), and "
         "'completed_at' is an ISO 8601 timestamp indicating when the batch job completed.",
     )
+
+
+class RetrieveStreamRequest(BaseModel):
+    starting_after: int = Field(
+        0, description="Sequence id to use as a cursor for pagination. Response will start streaming after this chunk sequence id"
+    )
+    include_pings: Optional[bool] = Field(
+        default=False,
+        description="Whether to include periodic keepalive ping messages in the stream to prevent connection timeouts.",
+    )
+    poll_interval: Optional[float] = Field(
+        default=0.1,
+        description="Seconds to wait between polls when no new data.",
+    )
+    batch_size: Optional[int] = Field(
+        default=100,
+        description="Number of entries to read per batch.",
+    )

letta/schemas/message.py

@@ -414,6 +414,8 @@ class Message(BaseMessage):
         except json.JSONDecodeError:
             raise ValueError(f"Failed to decode function return: {text_content}")
 
+        # if self.tool_call_id is None:
+        #     import pdb;pdb.set_trace()
         assert self.tool_call_id is not None
 
         return ToolReturnMessage(
@@ -844,7 +846,7 @@ class Message(BaseMessage):
             }
             content = []
             # COT / reasoning / thinking
-            if self.content is not None and len(self.content) > 1:
+            if self.content is not None and len(self.content) >= 1:
                 for content_part in self.content:
                     if isinstance(content_part, ReasoningContent):
                         content.append(
@@ -861,6 +863,13 @@ class Message(BaseMessage):
                                 "data": content_part.data,
                             }
                         )
+                    if isinstance(content_part, TextContent):
+                        content.append(
+                            {
+                                "type": "text",
+                                "text": content_part.text,
+                            }
+                        )
             elif text_content is not None:
                 content.append(
                     {

letta/schemas/providers/bedrock.py

@@ -18,6 +18,7 @@ logger = get_logger(__name__)
 class BedrockProvider(Provider):
     provider_type: Literal[ProviderType.bedrock] = Field(ProviderType.bedrock, description="The type of the provider.")
     provider_category: ProviderCategory = Field(ProviderCategory.base, description="The category of the provider (base or byok)")
+    access_key: str = Field(..., description="AWS secret access key for Bedrock.")
     region: str = Field(..., description="AWS region for Bedrock")
 
     async def bedrock_get_model_list_async(self) -> list[dict]:

letta/schemas/response_format.py

@@ -52,9 +52,9 @@ class JsonSchemaResponseFormat(ResponseFormat):
         description="The JSON schema of the response.",
     )
 
-    @field_validator("json_schema")
     @classmethod
-    def validate_json_schema(cls, v: dict[str, Any]) -> Dict[str, Any]:
+    @field_validator("json_schema")
+    def validate_json_schema(cls, v: Dict[str, Any]) -> Dict[str, Any]:
         """Validate that the provided schema is a valid JSON schema."""
         if "schema" not in v:
             raise ValueError("JSON schema should include a schema property")

letta/server/generate_openapi_schema.sh

@@ -1,12 +1,12 @@
 #!/bin/sh
 echo "Generating OpenAPI schema..."
 
-# check if poetry is installed
-if ! command -v poetry &> /dev/null
+# check if uv is installed
+if ! command -v uv &> /dev/null
 then
-    echo "Poetry could not be found. Please install poetry to generate the OpenAPI schema."
+    echo "uv could not be found. Please install uv to generate the OpenAPI schema."
     exit
 fi
 
 # generate OpenAPI schema
-poetry run python -c 'from letta.server.rest_api.app import app, generate_openapi_schema; generate_openapi_schema(app);'
+uv run python -c 'from letta.server.rest_api.app import app, generate_openapi_schema; generate_openapi_schema(app);'