letta-nightly 0.13.0.dev20251031104146__py3-none-any.whl → 0.13.1.dev20251031234110__py3-none-any.whl

letta/llm_api/anthropic_client.py

@@ -1,3 +1,4 @@
+import copy
 import json
 import logging
 import re
@@ -19,6 +20,7 @@ from letta.errors import (
     LLMConnectionError,
     LLMNotFoundError,
     LLMPermissionDeniedError,
+    LLMProviderOverloaded,
     LLMRateLimitError,
     LLMServerError,
     LLMTimeoutError,
@@ -229,6 +231,7 @@ class AnthropicClient(LLMClientBase):
         tools: Optional[List[dict]] = None,
         force_tool_call: Optional[str] = None,
         requires_subsequent_tool_call: bool = False,
+        tool_return_truncation_chars: Optional[int] = None,
     ) -> dict:
         # TODO: This needs to get cleaned up. The logic here is pretty confusing.
         # TODO: I really want to get rid of prefixing, it's a recipe for disaster code maintenance wise
@@ -334,6 +337,7 @@ class AnthropicClient(LLMClientBase):
             # if react, use native content + strip heartbeats
             native_content=is_v1,
             strip_request_heartbeat=is_v1,
+            tool_return_truncation_chars=tool_return_truncation_chars,
         )
 
         # Ensure first message is user
@@ -383,25 +387,53 @@ class AnthropicClient(LLMClientBase):
         else:
             anthropic_tools = None
 
-        # Detect presence of reasoning blocks anywhere in the final assistant message.
-        # Interleaved thinking is not guaranteed to be the first content part.
+        # Convert final thinking blocks to text to work around token counting endpoint limitation.
+        # The token counting endpoint rejects messages where the final content block is thinking,
+        # even though the main API supports this with the interleaved-thinking beta.
+        # We convert (not strip) to preserve accurate token counts.
+        # TODO: Remove this workaround if Anthropic fixes the token counting endpoint.
         thinking_enabled = False
+        messages_for_counting = messages
+
         if messages and len(messages) > 0:
-            last_assistant_message = next((m for m in reversed(messages) if m.get("role") == "assistant"), None)
-            if last_assistant_message:
-                content = last_assistant_message.get("content")
-                if isinstance(content, list):
-                    for part in content:
-                        if isinstance(part, dict) and part.get("type") in {"thinking", "redacted_thinking"}:
+            messages_for_counting = copy.deepcopy(messages)
+
+            # Scan all assistant messages and convert any final thinking blocks to text
+            for message in messages_for_counting:
+                if message.get("role") == "assistant":
+                    content = message.get("content")
+
+                    # Check for thinking in any format
+                    if isinstance(content, list) and len(content) > 0:
+                        # Check if message has any thinking blocks (to enable thinking mode)
+                        has_thinking = any(
+                            isinstance(part, dict) and part.get("type") in {"thinking", "redacted_thinking"} for part in content
+                        )
+                        if has_thinking:
                             thinking_enabled = True
-                            break
-                elif isinstance(content, str) and "<thinking>" in content:
-                    thinking_enabled = True
+
+                        # If final block is thinking, handle it
+                        last_block = content[-1]
+                        if isinstance(last_block, dict) and last_block.get("type") in {"thinking", "redacted_thinking"}:
+                            if len(content) == 1:
+                                # Thinking-only message: add text at end (don't convert the thinking)
+                                # API requires first block to be thinking when thinking is enabled
+                                content.append({"type": "text", "text": "."})
+                            else:
+                                # Multiple blocks: convert final thinking to text
+                                if last_block["type"] == "thinking":
+                                    content[-1] = {"type": "text", "text": last_block.get("thinking", "")}
+                                elif last_block["type"] == "redacted_thinking":
+                                    content[-1] = {"type": "text", "text": last_block.get("data", "[redacted]")}
+
+                    elif isinstance(content, str) and "<thinking>" in content:
+                        # Handle XML-style thinking in string content
+                        thinking_enabled = True
 
         try:
             count_params = {
                 "model": model or "claude-3-7-sonnet-20250219",
-                "messages": messages or [{"role": "user", "content": "hi"}],
+                "messages": messages_for_counting or [{"role": "user", "content": "hi"}],
                 "tools": anthropic_tools or [],
             }
 
@@ -444,6 +476,14 @@ class AnthropicClient(LLMClientBase):
 
     @trace_method
     def handle_llm_error(self, e: Exception) -> Exception:
+        # make sure to check for overflow errors, regardless of error type
+        error_str = str(e).lower()
+        if "prompt is too long" in error_str or "exceed context limit" in error_str or "exceeds context" in error_str:
+            logger.warning(f"[Anthropic] Context window exceeded: {str(e)}")
+            return ContextWindowExceededError(
+                message=f"Context window exceeded for Anthropic: {str(e)}",
+            )
+
         if isinstance(e, anthropic.APITimeoutError):
             logger.warning(f"[Anthropic] Request timeout: {e}")
             return LLMTimeoutError(
@@ -513,6 +553,11 @@ class AnthropicClient(LLMClientBase):
 
         if isinstance(e, anthropic.APIStatusError):
             logger.warning(f"[Anthropic] API status error: {str(e)}")
+            if "overloaded" in str(e).lower():
+                return LLMProviderOverloaded(
+                    message=f"Anthropic API is overloaded: {str(e)}",
+                    code=ErrorCode.INTERNAL_SERVER_ERROR,
+                )
             return LLMServerError(
                 message=f"Anthropic API error: {str(e)}",
                 code=ErrorCode.INTERNAL_SERVER_ERROR,

letta/llm_api/bedrock_client.py

@@ -71,6 +71,7 @@ class BedrockClient(AnthropicClient):
         tools: Optional[List[dict]] = None,
         force_tool_call: Optional[str] = None,
         requires_subsequent_tool_call: bool = False,
+        tool_return_truncation_chars: Optional[int] = None,
     ) -> dict:
         data = super().build_request_data(agent_type, messages, llm_config, tools, force_tool_call, requires_subsequent_tool_call)
         # remove disallowed fields

letta/llm_api/deepseek_client.py

@@ -59,7 +59,7 @@ def handle_assistant_message(assistant_message: AssistantMessage) -> AssistantMe
     return assistant_message
 
 
-def map_messages_to_deepseek_format(messages: List[ChatMessage]) -> List[_Message]:
+def map_messages_to_deepseek_format(messages: List[ChatMessage]) -> List["_Message"]:
     """
     Deepeek API has the following constraints: messages must be interleaved between user and assistant messages, ending on a user message.
     Tools are currently unstable for V3 and not supported for R1 in the API: https://api-docs.deepseek.com/guides/function_calling.
@@ -103,7 +103,7 @@ def map_messages_to_deepseek_format(messages: List[ChatMessage]) -> List[_Messag
 
 def build_deepseek_chat_completions_request(
     llm_config: LLMConfig,
-    messages: List[_Message],
+    messages: List["_Message"],
     user_id: Optional[str],
     functions: Optional[list],
     function_call: Optional[str],
@@ -340,6 +340,7 @@ class DeepseekClient(OpenAIClient):
         tools: Optional[List[dict]] = None,
         force_tool_call: Optional[str] = None,
         requires_subsequent_tool_call: bool = False,
+        tool_return_truncation_chars: Optional[int] = None,
     ) -> dict:
         # Override put_inner_thoughts_in_kwargs to False for DeepSeek
         llm_config.put_inner_thoughts_in_kwargs = False

letta/llm_api/google_vertex_client.py

@@ -291,6 +291,7 @@ class GoogleVertexClient(LLMClientBase):
         tools: List[dict],
         force_tool_call: Optional[str] = None,
         requires_subsequent_tool_call: bool = False,
+        tool_return_truncation_chars: Optional[int] = None,
     ) -> dict:
         """
         Constructs a request object in the expected data format for this client.

letta/llm_api/groq_client.py

@@ -30,6 +30,7 @@ class GroqClient(OpenAIClient):
         tools: Optional[List[dict]] = None,
         force_tool_call: Optional[str] = None,
         requires_subsequent_tool_call: bool = False,
+        tool_return_truncation_chars: Optional[int] = None,
     ) -> dict:
         data = super().build_request_data(agent_type, messages, llm_config, tools, force_tool_call, requires_subsequent_tool_call)
 

letta/llm_api/llm_client_base.py

@@ -47,13 +47,22 @@ class LLMClientBase:
         force_tool_call: Optional[str] = None,
         telemetry_manager: Optional["TelemetryManager"] = None,
         step_id: Optional[str] = None,
+        tool_return_truncation_chars: Optional[int] = None,
     ) -> Union[ChatCompletionResponse, Stream[ChatCompletionChunk]]:
         """
         Issues a request to the downstream model endpoint and parses response.
         If stream=True, returns a Stream[ChatCompletionChunk] that can be iterated over.
         Otherwise returns a ChatCompletionResponse.
         """
-        request_data = self.build_request_data(agent_type, messages, llm_config, tools, force_tool_call)
+        request_data = self.build_request_data(
+            agent_type,
+            messages,
+            llm_config,
+            tools,
+            force_tool_call,
+            requires_subsequent_tool_call=False,
+            tool_return_truncation_chars=tool_return_truncation_chars,
+        )
 
         try:
             log_event(name="llm_request_sent", attributes=request_data)
@@ -128,9 +137,14 @@ class LLMClientBase:
         tools: List[dict],
         force_tool_call: Optional[str] = None,
         requires_subsequent_tool_call: bool = False,
+        tool_return_truncation_chars: Optional[int] = None,
     ) -> dict:
         """
         Constructs a request object in the expected data format for this client.
+
+        Args:
+            tool_return_truncation_chars: If set, truncates tool return content to this many characters.
+                                         Used during summarization to avoid context window issues.
         """
         raise NotImplementedError
 

letta/llm_api/openai.py

@@ -624,8 +624,8 @@ def prepare_openai_payload(chat_completion_request: ChatCompletionRequest):
     data = chat_completion_request.model_dump(exclude_none=True)
 
     # add check otherwise will cause error: "Invalid value for 'parallel_tool_calls': 'parallel_tool_calls' is only allowed when 'tools' are specified."
-    if chat_completion_request.tools is not None:
-        data["parallel_tool_calls"] = False
+    if chat_completion_request.tools is not None and chat_completion_request.parallel_tool_calls is not None:
+        data["parallel_tool_calls"] = chat_completion_request.parallel_tool_calls
 
     # If functions == None, strip from the payload
     if "functions" in data and data["functions"] is None:

letta/llm_api/openai_client.py

@@ -64,6 +64,14 @@ def is_openai_reasoning_model(model: str) -> bool:
     return is_reasoning
 
 
+def does_not_support_minimal_reasoning(model: str) -> bool:
+    """Check if the model does not support minimal reasoning effort.
+
+    Currently, models that contain codex don't support minimal reasoning.
+    """
+    return "codex" in model.lower()
+
+
 def is_openai_5_model(model: str) -> bool:
     """Utility function to check if the model is a '5' model"""
     return model.startswith("gpt-5")
@@ -221,6 +229,7 @@ class OpenAIClient(LLMClientBase):
         tools: Optional[List[dict]] = None,  # Keep as dict for now as per base class
         force_tool_call: Optional[str] = None,
         requires_subsequent_tool_call: bool = False,
+        tool_return_truncation_chars: Optional[int] = None,
     ) -> dict:
         """
         Constructs a request object in the expected data format for the OpenAI Responses API.
@@ -228,7 +237,9 @@ class OpenAIClient(LLMClientBase):
         if llm_config.put_inner_thoughts_in_kwargs:
             raise ValueError("Inner thoughts in kwargs are not supported for the OpenAI Responses API")
 
-        openai_messages_list = PydanticMessage.to_openai_responses_dicts_from_list(messages)
+        openai_messages_list = PydanticMessage.to_openai_responses_dicts_from_list(
+            messages, tool_return_truncation_chars=tool_return_truncation_chars
+        )
         # Add multi-modal support for Responses API by rewriting user messages
         # into input_text/input_image parts.
         openai_messages_list = fill_image_content_in_responses_input(openai_messages_list, messages)
@@ -316,7 +327,7 @@ class OpenAIClient(LLMClientBase):
             tool_choice=tool_choice,
             max_output_tokens=llm_config.max_tokens,
             temperature=llm_config.temperature if supports_temperature_param(model) else None,
-            parallel_tool_calls=False,
+            parallel_tool_calls=llm_config.parallel_tool_calls if tools and supports_parallel_tool_calling(model) else False,
         )
 
         # Add verbosity control for GPT-5 models
@@ -341,7 +352,7 @@ class OpenAIClient(LLMClientBase):
 
         # Add parallel tool calling
         if tools and supports_parallel_tool_calling(model):
-            data.parallel_tool_calls = False
+            data.parallel_tool_calls = llm_config.parallel_tool_calls
 
         # always set user id for openai requests
         if self.actor:
@@ -369,6 +380,7 @@ class OpenAIClient(LLMClientBase):
         tools: Optional[List[dict]] = None,  # Keep as dict for now as per base class
         force_tool_call: Optional[str] = None,
         requires_subsequent_tool_call: bool = False,
+        tool_return_truncation_chars: Optional[int] = None,
     ) -> dict:
         """
         Constructs a request object in the expected data format for the OpenAI API.
@@ -382,6 +394,7 @@ class OpenAIClient(LLMClientBase):
                 tools=tools,
                 force_tool_call=force_tool_call,
                 requires_subsequent_tool_call=requires_subsequent_tool_call,
+                tool_return_truncation_chars=tool_return_truncation_chars,
             )
 
         if agent_type == AgentType.letta_v1_agent:
@@ -411,6 +424,7 @@ class OpenAIClient(LLMClientBase):
                 messages,
                 put_inner_thoughts_in_kwargs=llm_config.put_inner_thoughts_in_kwargs,
                 use_developer_message=use_developer_message,
+                tool_return_truncation_chars=tool_return_truncation_chars,
             )
         ]
 

letta/llm_api/xai_client.py

@@ -30,6 +30,7 @@ class XAIClient(OpenAIClient):
         tools: Optional[List[dict]] = None,
         force_tool_call: Optional[str] = None,
         requires_subsequent_tool_call: bool = False,
+        tool_return_truncation_chars: Optional[int] = None,
     ) -> dict:
         data = super().build_request_data(agent_type, messages, llm_config, tools, force_tool_call, requires_subsequent_tool_call)
 

letta/orm/organization.py

@@ -19,6 +19,7 @@ if TYPE_CHECKING:
     from letta.orm.passage import ArchivalPassage, SourcePassage
     from letta.orm.passage_tag import PassageTag
     from letta.orm.provider import Provider
+    from letta.orm.provider_trace import ProviderTrace
     from letta.orm.run import Run
     from letta.orm.sandbox_config import AgentEnvironmentVariable, SandboxConfig, SandboxEnvironmentVariable
     from letta.orm.tool import Tool
@@ -70,3 +71,6 @@ class Organization(SqlalchemyBase):
     )
     jobs: Mapped[List["Job"]] = relationship("Job", back_populates="organization", cascade="all, delete-orphan")
     runs: Mapped[List["Run"]] = relationship("Run", back_populates="organization", cascade="all, delete-orphan")
+    provider_traces: Mapped[List["ProviderTrace"]] = relationship(
+        "ProviderTrace", back_populates="organization", cascade="all, delete-orphan"
+    )

letta/orm/sqlalchemy_base.py

@@ -9,6 +9,7 @@ from sqlalchemy import Sequence, String, and_, delete, func, or_, select
 from sqlalchemy.exc import DBAPIError, IntegrityError, TimeoutError
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.orm import Mapped, Session, mapped_column
+from sqlalchemy.orm.exc import StaleDataError
 from sqlalchemy.orm.interfaces import ORMOption
 
 from letta.log import get_logger
@@ -625,6 +626,12 @@ class SqlalchemyBase(CommonSqlalchemyMetaMixins, Base):
             if not no_refresh:
                 await db_session.refresh(self)
             return self
+        except StaleDataError as e:
+            # This can occur when using optimistic locking (version_id_col) and:
+            # 1. The row doesn't exist (0 rows matched)
+            # 2. The version has changed (concurrent update)
+            # We convert this to NoResultFound to return a proper 404 error
+            raise NoResultFound(f"{self.__class__.__name__} with id '{self.id}' not found or was updated by another transaction") from e
         except (DBAPIError, IntegrityError) as e:
             self._handle_dbapi_error(e)
 

letta/otel/tracing.py

@@ -1,5 +1,6 @@
 import asyncio
 import inspect
+import itertools
 import re
 import time
 import traceback
@@ -227,11 +228,137 @@ def trace_method(func):
             if args and hasattr(args[0], "__class__"):
                 param_items = param_items[1:]
 
+            # Parameters to skip entirely (known to be large)
+            SKIP_PARAMS = {
+                "agent_state",
+                "messages",
+                "in_context_messages",
+                "message_sequence",
+                "content",
+                "tool_returns",
+                "memory",
+                "sources",
+                "context",
+                "resource_id",
+                "source_code",
+                "request_data",
+                "system",
+            }
+
+            # Max size for parameter value strings (1KB)
+            MAX_PARAM_SIZE = 1024
+            # Max total size for all parameters (100KB)
+            MAX_TOTAL_SIZE = 1024 * 100
+            total_size = 0
+
             for name, value in param_items:
-                # Convert value to string to avoid serialization issues
-                span.set_attribute(f"parameter.{name}", str(value))
-        except:
-            pass
+                try:
+                    # Check if we've exceeded total size limit
+                    if total_size > MAX_TOTAL_SIZE:
+                        span.set_attribute("parameters.truncated", True)
+                        span.set_attribute("parameters.truncated_reason", f"Total size exceeded {MAX_TOTAL_SIZE} bytes")
+                        break
+
+                    # Skip parameters known to be large
+                    if name in SKIP_PARAMS:
+                        # Try to extract ID for observability
+                        type_name = type(value).__name__
+                        id_info = ""
+
+                        try:
+                            # Handle lists/iterables (e.g., messages)
+                            if hasattr(value, "__iter__") and not isinstance(value, (str, bytes, dict)):
+                                ids = []
+                                count = 0
+                                # Use itertools.islice to avoid converting entire iterable
+                                for item in itertools.islice(value, 5):
+                                    count += 1
+                                    if hasattr(item, "id"):
+                                        ids.append(str(item.id))
+
+                                # Try to get total count if it's a sized iterable
+                                total_count = None
+                                if hasattr(value, "__len__"):
+                                    try:
+                                        total_count = len(value)
+                                    except (TypeError, AttributeError):
+                                        pass
+
+                                if ids:
+                                    suffix = ""
+                                    if total_count is not None and total_count > 5:
+                                        suffix = f"... ({total_count} total)"
+                                    elif count == 5:
+                                        suffix = "..."
+                                    id_info = f", ids=[{','.join(ids)}{suffix}]"
+                            # Handle single objects with id attribute
+                            elif hasattr(value, "id"):
+                                id_info = f", id={value.id}"
+                        except (TypeError, AttributeError, ValueError):
+                            pass
+
+                        param_value = f"<{type_name} (excluded{id_info})>"
+                        span.set_attribute(f"parameter.{name}", param_value)
+                        total_size += len(param_value)
+                        continue
+
+                    # Try repr first with length limit, fallback to str if needed
+                    str_value = None
+
+                    # For simple types, use str directly
+                    if isinstance(value, (str, int, float, bool, type(None))):
+                        str_value = str(value)
+                    else:
+                        # For complex objects, try to get a truncated representation
+                        try:
+                            # Test if str() works (some objects have broken __str__)
+                            try:
+                                test_str = str(value)
+                                # If str() works and is reasonable, use repr
+                                str_value = repr(value)
+                            except Exception:
+                                # If str() fails, mark as serialization failed
+                                raise ValueError("str() failed")
+
+                            # If repr is already too long, try to be smarter
+                            if len(str_value) > MAX_PARAM_SIZE * 2:
+                                # For collections, show just the type and size
+                                if hasattr(value, "__len__"):
+                                    try:
+                                        str_value = f"<{type(value).__name__} with {len(value)} items>"
+                                    except (TypeError, AttributeError):
+                                        str_value = f"<{type(value).__name__}>"
+                                else:
+                                    str_value = f"<{type(value).__name__}>"
+                        except (RecursionError, MemoryError, ValueError):
+                            # Handle cases where repr or str causes issues
+                            str_value = f"<serialization failed: {type(value).__name__}>"
+                        except Exception as e:
+                            # Fallback for any other issues
+                            str_value = f"<serialization failed: {type(e).__name__}>"
+
+                    # Apply size limit
+                    original_size = len(str_value)
+                    if original_size > MAX_PARAM_SIZE:
+                        str_value = str_value[:MAX_PARAM_SIZE] + f"... (truncated, original size: {original_size} chars)"
+
+                    span.set_attribute(f"parameter.{name}", str_value)
+                    total_size += len(str_value)
+
+                except (TypeError, ValueError, AttributeError, RecursionError, MemoryError) as e:
+                    try:
+                        error_msg = f"<serialization failed: {type(e).__name__}>"
+                        span.set_attribute(f"parameter.{name}", error_msg)
+                        total_size += len(error_msg)
+                    except Exception:
+                        # If even the fallback fails, skip this parameter
+                        pass
+
+        except (TypeError, ValueError, AttributeError) as e:
+            logger.debug(f"Failed to add parameters to span: {type(e).__name__}: {e}")
+        except Exception as e:
+            # Catch-all for any other unexpected exceptions
+            logger.debug(f"Unexpected error adding parameters to span: {type(e).__name__}: {e}")
 
     @wraps(func)
     async def async_wrapper(*args, **kwargs):

letta/schemas/agent_file.py

@@ -7,7 +7,7 @@ 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.enums import MessageRole, PrimitiveType
 from letta.schemas.file import FileAgent, FileAgentBase, FileMetadata, FileMetadataBase
 from letta.schemas.group import Group, GroupCreate
 from letta.schemas.letta_message import ApprovalReturn
@@ -42,7 +42,7 @@ class ImportResult:
 class MessageSchema(MessageCreate):
     """Message with human-readable ID for agent file"""
 
-    __id_prefix__ = "message"
+    __id_prefix__ = PrimitiveType.MESSAGE.value
     id: str = Field(..., description="Human-readable identifier for this message in the file")
 
     # Override the role field to accept all message roles, not just user/system/assistant
@@ -96,7 +96,7 @@ class MessageSchema(MessageCreate):
 class FileAgentSchema(FileAgentBase):
     """File-Agent relationship with human-readable ID for agent file"""
 
-    __id_prefix__ = "file_agent"
+    __id_prefix__ = PrimitiveType.FILE_AGENT.value
     id: str = Field(..., description="Human-readable identifier for this file-agent relationship in the file")
 
     @classmethod
@@ -120,7 +120,7 @@ class FileAgentSchema(FileAgentBase):
 class AgentSchema(CreateAgent):
     """Agent with human-readable ID for agent file"""
 
-    __id_prefix__ = "agent"
+    __id_prefix__ = PrimitiveType.AGENT.value
     id: str = Field(..., description="Human-readable identifier for this agent in the file")
     in_context_message_ids: List[str] = Field(
         default_factory=list, description="List of message IDs that are currently in the agent's context"
@@ -198,7 +198,7 @@ class AgentSchema(CreateAgent):
 class GroupSchema(GroupCreate):
     """Group with human-readable ID for agent file"""
 
-    __id_prefix__ = "group"
+    __id_prefix__ = PrimitiveType.GROUP.value
     id: str = Field(..., description="Human-readable identifier for this group in the file")
 
     @classmethod
@@ -220,7 +220,7 @@ class GroupSchema(GroupCreate):
 class BlockSchema(CreateBlock):
     """Block with human-readable ID for agent file"""
 
-    __id_prefix__ = "block"
+    __id_prefix__ = PrimitiveType.BLOCK.value
     id: str = Field(..., description="Human-readable identifier for this block in the file")
 
     @classmethod
@@ -246,7 +246,7 @@ class BlockSchema(CreateBlock):
 class FileSchema(FileMetadataBase):
     """File with human-readable ID for agent file"""
 
-    __id_prefix__ = "file"
+    __id_prefix__ = PrimitiveType.FILE.value
     id: str = Field(..., description="Human-readable identifier for this file in the file")
 
     @classmethod
@@ -276,7 +276,7 @@ class FileSchema(FileMetadataBase):
 class SourceSchema(SourceCreate):
     """Source with human-readable ID for agent file"""
 
-    __id_prefix__ = "source"
+    __id_prefix__ = PrimitiveType.SOURCE.value
     id: str = Field(..., description="Human-readable identifier for this source in the file")
 
     @classmethod
@@ -299,7 +299,7 @@ class SourceSchema(SourceCreate):
 class ToolSchema(Tool):
     """Tool with human-readable ID for agent file"""
 
-    __id_prefix__ = "tool"
+    __id_prefix__ = PrimitiveType.TOOL.value
     id: str = Field(..., description="Human-readable identifier for this tool in the file")
 
     @classmethod
@@ -311,7 +311,7 @@ class ToolSchema(Tool):
 class MCPServerSchema(BaseModel):
     """MCP server schema for agent files with remapped ID."""
 
-    __id_prefix__ = "mcp_server"
+    __id_prefix__ = PrimitiveType.MCP_SERVER.value
 
     id: str = Field(..., description="Human-readable MCP server ID")
     server_type: str

letta/schemas/block.py

@@ -21,9 +21,9 @@ class BaseBlock(LettaBase, validate_assignment=True):
 
     project_id: Optional[str] = Field(None, description="The associated project id.")
     # template data (optional)
-    template_name: Optional[str] = Field(None, description="Name of the block if it is a template.", alias="name")
+    template_name: Optional[str] = Field(None, description="Name of the block if it is a template.")
     is_template: bool = Field(False, description="Whether the block is a template (e.g. saved human/persona options).")
-    template_id: Optional[str] = Field(None, description="The id of the template.", alias="name")
+    template_id: Optional[str] = Field(None, description="The id of the template.")
     base_template_id: Optional[str] = Field(None, description="The base template id of the block.")
     deployment_id: Optional[str] = Field(None, description="The id of the deployment.")
     entity_id: Optional[str] = Field(None, description="The id of the entity within the template.")
@@ -102,6 +102,25 @@ class Block(BaseBlock):
     last_updated_by_id: Optional[str] = Field(None, description="The id of the user that last updated this Block.")
 
 
+class BlockResponse(Block):
+    id: str = Field(
+        ...,
+        description="The id of the block.",
+    )
+    template_name: Optional[str] = Field(
+        None, description="(Deprecated) The name of the block template (if it is a template).", deprecated=True
+    )
+    template_id: Optional[str] = Field(None, description="(Deprecated) The id of the template.", deprecated=True)
+    base_template_id: Optional[str] = Field(None, description="(Deprecated) The base template id of the block.", deprecated=True)
+    deployment_id: Optional[str] = Field(None, description="(Deprecated) The id of the deployment.", deprecated=True)
+    entity_id: Optional[str] = Field(None, description="(Deprecated) The id of the entity within the template.", deprecated=True)
+    preserve_on_migration: Optional[bool] = Field(
+        False, description="(Deprecated) Preserve the block on template migration.", deprecated=True
+    )
+    read_only: bool = Field(False, description="(Deprecated) Whether the agent has read-only access to the block.", deprecated=True)
+    hidden: Optional[bool] = Field(None, description="(Deprecated) If set to True, the block will be hidden.", deprecated=True)
+
+
 class FileBlock(Block):
     file_id: str = Field(..., description="Unique identifier of the file.")
     source_id: str = Field(..., description="Unique identifier of the source.")
@@ -149,7 +168,7 @@ class CreateBlock(BaseBlock):
     project_id: Optional[str] = Field(None, description="The associated project id.")
     # block templates
     is_template: bool = False
-    template_name: Optional[str] = Field(None, description="Name of the block if it is a template.", alias="name")
+    template_name: Optional[str] = Field(None, description="Name of the block if it is a template.")
 
     @model_validator(mode="before")
     @classmethod

letta/schemas/enums.py

@@ -26,6 +26,27 @@ class PrimitiveType(str, Enum):
     STEP = "step"
     IDENTITY = "identity"
 
+    # Infrastructure types
+    MCP_SERVER = "mcp_server"
+    MCP_OAUTH = "mcp-oauth"
+    FILE_AGENT = "file_agent"
+
+    # Configuration types
+    SANDBOX_ENV = "sandbox-env"
+    AGENT_ENV = "agent-env"
+
+    # Core entity types
+    USER = "user"
+    ORGANIZATION = "org"
+    TOOL_RULE = "tool_rule"
+
+    # Batch processing types
+    BATCH_ITEM = "batch_item"
+    BATCH_REQUEST = "batch_req"
+
+    # Telemetry types
+    PROVIDER_TRACE = "provider_trace"
+
 
 class ProviderType(str, Enum):
     anthropic = "anthropic"