letta-nightly 0.7.29.dev20250602104315__py3-none-any.whl → 0.8.0.dev20250604104349__py3-none-any.whl

letta/llm_api/anthropic_client.py

@@ -53,13 +53,13 @@ class AnthropicClient(LLMClientBase):
 
     @trace_method
     async def request_async(self, request_data: dict, llm_config: LLMConfig) -> dict:
-        client = self._get_anthropic_client(llm_config, async_client=True)
+        client = await self._get_anthropic_client_async(llm_config, async_client=True)
         response = await client.beta.messages.create(**request_data, betas=["tools-2024-04-04"])
         return response.model_dump()
 
     @trace_method
     async def stream_async(self, request_data: dict, llm_config: LLMConfig) -> AsyncStream[BetaRawMessageStreamEvent]:
-        client = self._get_anthropic_client(llm_config, async_client=True)
+        client = await self._get_anthropic_client_async(llm_config, async_client=True)
         request_data["stream"] = True
         return await client.beta.messages.create(**request_data, betas=["tools-2024-04-04"])
 
@@ -99,7 +99,7 @@ class AnthropicClient(LLMClientBase):
                 for agent_id in agent_messages_mapping
             }
 
-            client = self._get_anthropic_client(list(agent_llm_config_mapping.values())[0], async_client=True)
+            client = await self._get_anthropic_client_async(list(agent_llm_config_mapping.values())[0], async_client=True)
 
             anthropic_requests = [
                 Request(custom_id=agent_id, params=MessageCreateParamsNonStreaming(**params)) for agent_id, params in requests.items()
@@ -134,6 +134,26 @@ class AnthropicClient(LLMClientBase):
             else anthropic.Anthropic(max_retries=model_settings.anthropic_max_retries)
         )
 
+    @trace_method
+    async def _get_anthropic_client_async(
+        self, llm_config: LLMConfig, async_client: bool = False
+    ) -> Union[anthropic.AsyncAnthropic, anthropic.Anthropic]:
+        override_key = None
+        if llm_config.provider_category == ProviderCategory.byok:
+            override_key = await ProviderManager().get_override_key_async(llm_config.provider_name, actor=self.actor)
+
+        if async_client:
+            return (
+                anthropic.AsyncAnthropic(api_key=override_key, max_retries=model_settings.anthropic_max_retries)
+                if override_key
+                else anthropic.AsyncAnthropic(max_retries=model_settings.anthropic_max_retries)
+            )
+        return (
+            anthropic.Anthropic(api_key=override_key, max_retries=model_settings.anthropic_max_retries)
+            if override_key
+            else anthropic.Anthropic(max_retries=model_settings.anthropic_max_retries)
+        )
+
     @trace_method
     def build_request_data(
         self,
@@ -268,6 +288,7 @@ class AnthropicClient(LLMClientBase):
             token_count -= 8
         return token_count
 
+    @trace_method
     def handle_llm_error(self, e: Exception) -> Exception:
         if isinstance(e, anthropic.APIConnectionError):
             logger.warning(f"[Anthropic] API connection error: {e.__cause__}")

letta/llm_api/google_ai_client.py

@@ -7,10 +7,7 @@ from letta.errors import ErrorCode, LLMAuthenticationError, LLMError
 from letta.llm_api.google_constants import GOOGLE_MODEL_FOR_API_KEY_CHECK
 from letta.llm_api.google_vertex_client import GoogleVertexClient
 from letta.log import get_logger
-from letta.schemas.llm_config import LLMConfig
-from letta.schemas.message import Message as PydanticMessage
 from letta.settings import model_settings
-from letta.tracing import trace_method
 
 logger = get_logger(__name__)
 
@@ -20,18 +17,6 @@ class GoogleAIClient(GoogleVertexClient):
     def _get_client(self):
         return genai.Client(api_key=model_settings.gemini_api_key)
 
-    @trace_method
-    def build_request_data(
-        self,
-        messages: List[PydanticMessage],
-        llm_config: LLMConfig,
-        tools: List[dict],
-        force_tool_call: Optional[str] = None,
-    ) -> dict:
-        request = super().build_request_data(messages, llm_config, tools, force_tool_call)
-        del request["config"]["thinking_config"]
-        return request
-
 
 def get_gemini_endpoint_and_headers(
     base_url: str, model: Optional[str], api_key: str, key_in_header: bool = True, generate_content: bool = False

letta/llm_api/google_vertex_client.py

@@ -241,13 +241,14 @@ class GoogleVertexClient(LLMClientBase):
             )
             request_data["config"]["tool_config"] = tool_config.model_dump()
 
-        # Add thinking_config
+        # Add thinking_config for flash
         # If enable_reasoner is False, set thinking_budget to 0
         # Otherwise, use the value from max_reasoning_tokens
-        thinking_config = ThinkingConfig(
-            thinking_budget=llm_config.max_reasoning_tokens if llm_config.enable_reasoner else 0,
-        )
-        request_data["config"]["thinking_config"] = thinking_config.model_dump()
+        if "flash" in llm_config.model:
+            thinking_config = ThinkingConfig(
+                thinking_budget=llm_config.max_reasoning_tokens if llm_config.enable_reasoner else 0,
+            )
+            request_data["config"]["thinking_config"] = thinking_config.model_dump()
 
         return request_data
 

letta/llm_api/llm_client_base.py

@@ -6,6 +6,7 @@ from openai import AsyncStream, Stream
 from openai.types.chat.chat_completion_chunk import ChatCompletionChunk
 
 from letta.errors import LLMError
+from letta.schemas.embedding_config import EmbeddingConfig
 from letta.schemas.llm_config import LLMConfig
 from letta.schemas.message import Message
 from letta.schemas.openai.chat_completion_response import ChatCompletionResponse
@@ -138,6 +139,20 @@ class LLMClientBase:
         """
         raise NotImplementedError
 
+    @abstractmethod
+    async def request_embeddings(self, texts: List[str], embedding_config: EmbeddingConfig) -> List[List[float]]:
+        """
+        Generate embeddings for a batch of texts.
+
+        Args:
+            texts (List[str]): List of texts to generate embeddings for.
+            embedding_config (EmbeddingConfig): Configuration for the embedding model.
+
+        Returns:
+            embeddings (List[List[float]]): List of embeddings for the input texts.
+        """
+        raise NotImplementedError
+
     @abstractmethod
     def convert_response_to_chat_completion(
         self,

letta/llm_api/openai.py

@@ -226,7 +226,7 @@ def build_openai_chat_completions_request(
             tool_choice=tool_choice,
             user=str(user_id),
             max_completion_tokens=llm_config.max_tokens,
-            temperature=llm_config.temperature if supports_temperature_param(model) else None,
+            temperature=llm_config.temperature if supports_temperature_param(model) else 1.0,
             reasoning_effort=llm_config.reasoning_effort,
         )
     else:
@@ -237,7 +237,7 @@ def build_openai_chat_completions_request(
             function_call=function_call,
             user=str(user_id),
             max_completion_tokens=llm_config.max_tokens,
-            temperature=1.0 if llm_config.enable_reasoner else llm_config.temperature,
+            temperature=llm_config.temperature if supports_temperature_param(model) else 1.0,
             reasoning_effort=llm_config.reasoning_effort,
         )
         # https://platform.openai.com/docs/guides/text-generation/json-mode

letta/llm_api/openai_client.py

@@ -12,6 +12,7 @@ from letta.errors import (
     LLMAuthenticationError,
     LLMBadRequestError,
     LLMConnectionError,
+    LLMContextWindowExceededError,
     LLMNotFoundError,
     LLMPermissionDeniedError,
     LLMRateLimitError,
@@ -22,6 +23,7 @@ from letta.llm_api.helpers import add_inner_thoughts_to_functions, convert_to_st
 from letta.llm_api.llm_client_base import LLMClientBase
 from letta.local_llm.constants import INNER_THOUGHTS_KWARG, INNER_THOUGHTS_KWARG_DESCRIPTION, INNER_THOUGHTS_KWARG_DESCRIPTION_GO_FIRST
 from letta.log import get_logger
+from letta.schemas.embedding_config import EmbeddingConfig
 from letta.schemas.enums import ProviderCategory, ProviderType
 from letta.schemas.llm_config import LLMConfig
 from letta.schemas.message import Message as PydanticMessage
@@ -125,6 +127,35 @@ class OpenAIClient(LLMClientBase):
 
         return kwargs
 
+    def _prepare_client_kwargs_embedding(self, embedding_config: EmbeddingConfig) -> dict:
+        api_key = None
+        if embedding_config.embedding_endpoint_type == ProviderType.together:
+            api_key = model_settings.together_api_key or os.environ.get("TOGETHER_API_KEY")
+
+        if not api_key:
+            api_key = model_settings.openai_api_key or os.environ.get("OPENAI_API_KEY")
+        # supposedly the openai python client requires a dummy API key
+        api_key = api_key or "DUMMY_API_KEY"
+        kwargs = {"api_key": api_key, "base_url": embedding_config.embedding_endpoint}
+        return kwargs
+
+    async def _prepare_client_kwargs_async(self, llm_config: LLMConfig) -> dict:
+        api_key = None
+        if llm_config.provider_category == ProviderCategory.byok:
+            from letta.services.provider_manager import ProviderManager
+
+            api_key = await ProviderManager().get_override_key_async(llm_config.provider_name, actor=self.actor)
+        if llm_config.model_endpoint_type == ProviderType.together:
+            api_key = model_settings.together_api_key or os.environ.get("TOGETHER_API_KEY")
+
+        if not api_key:
+            api_key = model_settings.openai_api_key or os.environ.get("OPENAI_API_KEY")
+        # supposedly the openai python client requires a dummy API key
+        api_key = api_key or "DUMMY_API_KEY"
+        kwargs = {"api_key": api_key, "base_url": llm_config.model_endpoint}
+
+        return kwargs
+
     @trace_method
     def build_request_data(
         self,
@@ -190,7 +221,6 @@ class OpenAIClient(LLMClientBase):
             # NOTE: the reasoners that don't support temperature require 1.0, not None
             temperature=llm_config.temperature if supports_temperature_param(model) else 1.0,
         )
-
         # always set user id for openai requests
         if self.actor:
             data.user = self.actor.id
@@ -231,7 +261,8 @@ class OpenAIClient(LLMClientBase):
         """
         Performs underlying asynchronous request to OpenAI API and returns raw response dict.
         """
-        client = AsyncOpenAI(**self._prepare_client_kwargs(llm_config))
+        kwargs = await self._prepare_client_kwargs_async(llm_config)
+        client = AsyncOpenAI(**kwargs)
         response: ChatCompletion = await client.chat.completions.create(**request_data)
         return response.model_dump()
 
@@ -262,16 +293,29 @@ class OpenAIClient(LLMClientBase):
 
         return chat_completion_response
 
+    @trace_method
     async def stream_async(self, request_data: dict, llm_config: LLMConfig) -> AsyncStream[ChatCompletionChunk]:
         """
         Performs underlying asynchronous streaming request to OpenAI and returns the async stream iterator.
         """
-        client = AsyncOpenAI(**self._prepare_client_kwargs(llm_config))
+        kwargs = await self._prepare_client_kwargs_async(llm_config)
+        client = AsyncOpenAI(**kwargs)
         response_stream: AsyncStream[ChatCompletionChunk] = await client.chat.completions.create(
             **request_data, stream=True, stream_options={"include_usage": True}
         )
         return response_stream
 
+    @trace_method
+    async def request_embeddings(self, inputs: List[str], embedding_config: EmbeddingConfig) -> List[dict]:
+        """Request embeddings given texts and embedding config"""
+        kwargs = self._prepare_client_kwargs_embedding(embedding_config)
+        client = AsyncOpenAI(**kwargs)
+        response = await client.embeddings.create(model=embedding_config.embedding_model, input=inputs)
+
+        # TODO: add total usage
+        return [r.embedding for r in response.data]
+
+    @trace_method
     def handle_llm_error(self, e: Exception) -> Exception:
         """
         Maps OpenAI-specific errors to common LLMError types.
@@ -297,11 +341,19 @@ class OpenAIClient(LLMClientBase):
             # BadRequestError can signify different issues (e.g., invalid args, context length)
             # Check message content if finer-grained errors are needed
             # Example: if "context_length_exceeded" in str(e): return LLMContextLengthExceededError(...)
-            return LLMBadRequestError(
-                message=f"Bad request to OpenAI: {str(e)}",
-                code=ErrorCode.INVALID_ARGUMENT,  # Or more specific if detectable
-                details=e.body,
-            )
+            # TODO: This is a super soft check. Not sure if we can do better, needs more investigation.
+            if "context" in str(e):
+                return LLMContextWindowExceededError(
+                    message=f"Bad request to OpenAI (context length exceeded): {str(e)}",
+                    code=ErrorCode.INVALID_ARGUMENT,  # Or more specific if detectable
+                    details=e.body,
+                )
+            else:
+                return LLMBadRequestError(
+                    message=f"Bad request to OpenAI: {str(e)}",
+                    code=ErrorCode.INVALID_ARGUMENT,  # Or more specific if detectable
+                    details=e.body,
+                )
 
         if isinstance(e, openai.AuthenticationError):
             logger.error(f"[OpenAI] Authentication error (401): {str(e)}")  # More severe log level

letta/orm/__init__.py

@@ -5,6 +5,7 @@ from letta.orm.block import Block
 from letta.orm.block_history import BlockHistory
 from letta.orm.blocks_agents import BlocksAgents
 from letta.orm.file import FileMetadata
+from letta.orm.files_agents import FileAgent
 from letta.orm.group import Group
 from letta.orm.groups_agents import GroupsAgents
 from letta.orm.groups_blocks import GroupsBlocks
@@ -15,6 +16,7 @@ from letta.orm.job import Job
 from letta.orm.job_messages import JobMessage
 from letta.orm.llm_batch_items import LLMBatchItem
 from letta.orm.llm_batch_job import LLMBatchJob
+from letta.orm.mcp_server import MCPServer
 from letta.orm.message import Message
 from letta.orm.organization import Organization
 from letta.orm.passage import AgentPassage, BasePassage, SourcePassage

letta/orm/agent.py

@@ -1,3 +1,4 @@
+import asyncio
 import uuid
 from typing import TYPE_CHECKING, List, Optional, Set
 
@@ -21,6 +22,7 @@ from letta.schemas.tool_rule import ToolRule
 
 if TYPE_CHECKING:
     from letta.orm.agents_tags import AgentsTags
+    from letta.orm.files_agents import FileAgent
     from letta.orm.identity import Identity
     from letta.orm.organization import Organization
     from letta.orm.source import Source
@@ -125,6 +127,12 @@ class Agent(SqlalchemyBase, OrganizationMixin, AsyncAttrs):
         back_populates="manager_agent",
     )
     batch_items: Mapped[List["LLMBatchItem"]] = relationship("LLMBatchItem", back_populates="agent", lazy="selectin")
+    file_agents: Mapped[List["FileAgent"]] = relationship(
+        "FileAgent",
+        back_populates="agent",
+        cascade="all, delete-orphan",
+        lazy="selectin",
+    )
 
     def to_pydantic(self, include_relationships: Optional[Set[str]] = None) -> PydanticAgentState:
         """
@@ -166,6 +174,8 @@ class Agent(SqlalchemyBase, OrganizationMixin, AsyncAttrs):
             "last_updated_by_id": self.last_updated_by_id,
             "created_at": self.created_at,
             "updated_at": self.updated_at,
+            "enable_sleeptime": self.enable_sleeptime,
+            "response_format": self.response_format,
             # optional field defaults
             "tags": [],
             "tools": [],
@@ -174,8 +184,6 @@ class Agent(SqlalchemyBase, OrganizationMixin, AsyncAttrs):
             "identity_ids": [],
             "multi_agent_group": None,
             "tool_exec_environment_variables": [],
-            "enable_sleeptime": None,
-            "response_format": self.response_format,
         }
 
         # Optional fields: only included if requested
@@ -185,12 +193,12 @@ class Agent(SqlalchemyBase, OrganizationMixin, AsyncAttrs):
             "sources": lambda: [s.to_pydantic() for s in self.sources],
             "memory": lambda: Memory(
                 blocks=[b.to_pydantic() for b in self.core_memory],
+                file_blocks=[block for b in self.file_agents if (block := b.to_pydantic_block()) is not None],
                 prompt_template=get_prompt_template_for_agent_type(self.agent_type),
             ),
             "identity_ids": lambda: [i.id for i in self.identities],
             "multi_agent_group": lambda: self.multi_agent_group,
             "tool_exec_environment_variables": lambda: self.tool_exec_environment_variables,
-            "enable_sleeptime": lambda: self.enable_sleeptime,
         }
 
         include_relationships = set(optional_fields.keys() if include_relationships is None else include_relationships)
@@ -242,15 +250,7 @@ class Agent(SqlalchemyBase, OrganizationMixin, AsyncAttrs):
             "last_updated_by_id": self.last_updated_by_id,
             "created_at": self.created_at,
             "updated_at": self.updated_at,
-            # optional field defaults
-            "tags": [],
-            "tools": [],
-            "sources": [],
-            "memory": Memory(blocks=[]),
-            "identity_ids": [],
-            "multi_agent_group": None,
-            "tool_exec_environment_variables": [],
-            "enable_sleeptime": None,
+            "enable_sleeptime": self.enable_sleeptime,
             "response_format": self.response_format,
         }
         optional_fields = {
@@ -261,43 +261,45 @@ class Agent(SqlalchemyBase, OrganizationMixin, AsyncAttrs):
             "identity_ids": [],
             "multi_agent_group": None,
             "tool_exec_environment_variables": [],
-            "enable_sleeptime": None,
-            "response_format": self.response_format,
         }
 
         # Initialize include_relationships to an empty set if it's None
         include_relationships = set(optional_fields.keys() if include_relationships is None else include_relationships)
 
-        # Only load requested relationships
-        if "tags" in include_relationships:
-            tags = await self.awaitable_attrs.tags
-            state["tags"] = [t.tag for t in tags]
-
-        if "tools" in include_relationships:
-            state["tools"] = await self.awaitable_attrs.tools
+        async def empty_list_async():
+            return []
 
-        if "sources" in include_relationships:
-            sources = await self.awaitable_attrs.sources
-            state["sources"] = [s.to_pydantic() for s in sources]
+        async def none_async():
+            return None
 
-        if "memory" in include_relationships:
-            memory_blocks = await self.awaitable_attrs.core_memory
-            state["memory"] = Memory(
-                blocks=[b.to_pydantic() for b in memory_blocks],
-                prompt_template=get_prompt_template_for_agent_type(self.agent_type),
-            )
-
-        if "identity_ids" in include_relationships:
-            identities = await self.awaitable_attrs.identities
-            state["identity_ids"] = [i.id for i in identities]
-
-        if "multi_agent_group" in include_relationships:
-            state["multi_agent_group"] = await self.awaitable_attrs.multi_agent_group
-
-        if "tool_exec_environment_variables" in include_relationships:
-            state["tool_exec_environment_variables"] = await self.awaitable_attrs.tool_exec_environment_variables
-
-        if "enable_sleeptime" in include_relationships:
-            state["enable_sleeptime"] = await self.awaitable_attrs.enable_sleeptime
+        # Only load requested relationships
+        tags = self.awaitable_attrs.tags if "tags" in include_relationships else empty_list_async()
+        tools = self.awaitable_attrs.tools if "tools" in include_relationships else empty_list_async()
+        sources = self.awaitable_attrs.sources if "sources" in include_relationships else empty_list_async()
+        memory = self.awaitable_attrs.core_memory if "memory" in include_relationships else empty_list_async()
+        identities = self.awaitable_attrs.identities if "identity_ids" in include_relationships else empty_list_async()
+        multi_agent_group = self.awaitable_attrs.multi_agent_group if "multi_agent_group" in include_relationships else none_async()
+        tool_exec_environment_variables = (
+            self.awaitable_attrs.tool_exec_environment_variables
+            if "tool_exec_environment_variables" in include_relationships
+            else empty_list_async()
+        )
+        file_agents = self.awaitable_attrs.file_agents if "memory" in include_relationships else empty_list_async()
+
+        (tags, tools, sources, memory, identities, multi_agent_group, tool_exec_environment_variables, file_agents) = await asyncio.gather(
+            tags, tools, sources, memory, identities, multi_agent_group, tool_exec_environment_variables, file_agents
+        )
+
+        state["tags"] = [t.tag for t in tags]
+        state["tools"] = [t.to_pydantic() for t in tools]
+        state["sources"] = [s.to_pydantic() for s in sources]
+        state["memory"] = Memory(
+            blocks=[m.to_pydantic() for m in memory],
+            file_blocks=[block for b in self.file_agents if (block := b.to_pydantic_block()) is not None],
+            prompt_template=get_prompt_template_for_agent_type(self.agent_type),
+        )
+        state["identity_ids"] = [i.id for i in identities]
+        state["multi_agent_group"] = multi_agent_group
+        state["tool_exec_environment_variables"] = tool_exec_environment_variables
 
         return self.__pydantic_model__(**state)

letta/orm/base.py

@@ -69,8 +69,6 @@ class CommonSqlalchemyMetaMixins(Base):
         """returns the user id for the specified property"""
         full_prop = f"_{prop}_by_id"
         prop_value = getattr(self, full_prop, None)
-        if not prop_value:
-            return
         return prop_value
 
     def _user_id_setter(self, prop: str, value: str) -> None:

letta/orm/block.py

@@ -35,6 +35,7 @@ class Block(OrganizationMixin, SqlalchemyBase):
     is_template: Mapped[bool] = mapped_column(
         doc="whether the block is a template (e.g. saved human/persona options as baselines for other templates)", default=False
     )
+    preserve_on_migration: Mapped[Optional[bool]] = mapped_column(doc="preserve the block on template migration", default=False)
     value: Mapped[str] = mapped_column(doc="Text content of the block for the respective section of core memory.")
     limit: Mapped[BigInteger] = mapped_column(Integer, default=CORE_MEMORY_BLOCK_CHAR_LIMIT, doc="Character limit of the block.")
     metadata_: Mapped[Optional[dict]] = mapped_column(JSON, default={}, doc="arbitrary information related to the block.")

letta/orm/custom_columns.py

@@ -7,6 +7,7 @@ from letta.helpers.converters import (
     deserialize_create_batch_response,
     deserialize_embedding_config,
     deserialize_llm_config,
+    deserialize_mcp_stdio_config,
     deserialize_message_content,
     deserialize_poll_batch_response,
     deserialize_response_format,
@@ -19,6 +20,7 @@ from letta.helpers.converters import (
     serialize_create_batch_response,
     serialize_embedding_config,
     serialize_llm_config,
+    serialize_mcp_stdio_config,
     serialize_message_content,
     serialize_poll_batch_response,
     serialize_response_format,
@@ -183,3 +185,14 @@ class ResponseFormatColumn(TypeDecorator):
 
     def process_result_value(self, value, dialect):
         return deserialize_response_format(value)
+
+
+class MCPStdioServerConfigColumn(TypeDecorator):
+    impl = JSON
+    cache_ok = True
+
+    def process_bind_param(self, value, dialect):
+        return serialize_mcp_stdio_config(value)
+
+    def process_result_value(self, value, dialect):
+        return deserialize_mcp_stdio_config(value)

letta/orm/enums.py

@@ -32,3 +32,8 @@ class ActorType(str, Enum):
     LETTA_USER = "letta_user"
     LETTA_AGENT = "letta_agent"
     LETTA_SYSTEM = "letta_system"
+
+
+class MCPServerType(str, Enum):
+    SSE = "sse"
+    STDIO = "stdio"

letta/orm/file.py

@@ -8,13 +8,14 @@ from letta.orm.sqlalchemy_base import SqlalchemyBase
 from letta.schemas.file import FileMetadata as PydanticFileMetadata
 
 if TYPE_CHECKING:
+    from letta.orm.files_agents import FileAgent
     from letta.orm.organization import Organization
     from letta.orm.passage import SourcePassage
     from letta.orm.source import Source
 
 
 class FileMetadata(SqlalchemyBase, OrganizationMixin, SourceMixin):
-    """Represents metadata for an uploaded file."""
+    """Represents an uploaded file."""
 
     __tablename__ = "files"
     __pydantic_model__ = PydanticFileMetadata
@@ -32,3 +33,4 @@ class FileMetadata(SqlalchemyBase, OrganizationMixin, SourceMixin):
     source_passages: Mapped[List["SourcePassage"]] = relationship(
         "SourcePassage", back_populates="file", lazy="selectin", cascade="all, delete-orphan"
     )
+    file_agents: Mapped[List["FileAgent"]] = relationship("FileAgent", back_populates="file", lazy="selectin")

letta/orm/files_agents.py

@@ -0,0 +1,68 @@
+import uuid
+from datetime import datetime
+from typing import TYPE_CHECKING, Optional
+
+from sqlalchemy import Boolean, DateTime, ForeignKey, Index, String, Text, UniqueConstraint, func
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from letta.orm.mixins import OrganizationMixin
+from letta.orm.sqlalchemy_base import SqlalchemyBase
+from letta.schemas.block import Block as PydanticBlock
+from letta.schemas.file import FileAgent as PydanticFileAgent
+
+if TYPE_CHECKING:
+    from letta.orm.file import FileMetadata
+
+
+class FileAgent(SqlalchemyBase, OrganizationMixin):
+    """
+    Join table between File and Agent.
+
+    Tracks whether a file is currently “open” for the agent and
+    the specific excerpt (grepped section) the agent is looking at.
+    """
+
+    __tablename__ = "files_agents"
+    __table_args__ = (
+        Index("ix_files_agents_file_id_agent_id", "file_id", "agent_id"),
+        UniqueConstraint("file_id", "agent_id", name="uq_files_agents_file_agent"),
+    )
+    __pydantic_model__ = PydanticFileAgent
+
+    # TODO: We want to migrate all the ORM models to do this, so we will need to move this to the SqlalchemyBase
+    # TODO: Some still rely on the Pydantic object to do this
+    id: Mapped[str] = mapped_column(String, primary_key=True, default=lambda: f"file_agent-{uuid.uuid4()}")
+    file_id: Mapped[str] = mapped_column(String, ForeignKey("files.id", ondelete="CASCADE"), primary_key=True, doc="ID of the file.")
+    agent_id: Mapped[str] = mapped_column(String, ForeignKey("agents.id", ondelete="CASCADE"), primary_key=True, doc="ID of the agent.")
+
+    is_open: Mapped[bool] = mapped_column(Boolean, nullable=False, default=True, doc="True if the agent currently has the file open.")
+    visible_content: Mapped[Optional[str]] = mapped_column(Text, nullable=True, doc="Portion of the file the agent is focused on.")
+    last_accessed_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=func.now(),
+        onupdate=func.now(),
+        nullable=False,
+        doc="UTC timestamp when this agent last accessed the file.",
+    )
+
+    # relationships
+    agent: Mapped["Agent"] = relationship(
+        "Agent",
+        back_populates="file_agents",
+        lazy="selectin",
+    )
+    file: Mapped["FileMetadata"] = relationship(
+        "FileMetadata",
+        foreign_keys=[file_id],
+        lazy="selectin",
+    )
+
+    # TODO: This is temporary as we figure out if we want FileBlock as a first class citizen
+    def to_pydantic_block(self) -> PydanticBlock:
+        visible_content = self.visible_content if self.visible_content and self.is_open else ""
+        return PydanticBlock(
+            organization_id=self.organization_id,
+            value=visible_content,
+            label=self.file.file_name,
+            read_only=True,
+        )

letta/orm/mcp_server.py

@@ -0,0 +1,48 @@
+from typing import TYPE_CHECKING, Optional
+
+from sqlalchemy import JSON, String, UniqueConstraint
+from sqlalchemy.orm import Mapped, mapped_column
+
+from letta.functions.mcp_client.types import StdioServerConfig
+from letta.orm.custom_columns import MCPStdioServerConfigColumn
+
+# TODO everything in functions should live in this model
+from letta.orm.enums import MCPServerType
+from letta.orm.mixins import OrganizationMixin
+from letta.orm.sqlalchemy_base import SqlalchemyBase
+from letta.schemas.mcp import MCPServer
+
+if TYPE_CHECKING:
+    pass
+
+
+class MCPServer(SqlalchemyBase, OrganizationMixin):
+    """Represents a registered MCP server"""
+
+    __tablename__ = "mcp_server"
+    __pydantic_model__ = MCPServer
+
+    # Add unique constraint on (name, _organization_id)
+    # An organization should not have multiple tools with the same name
+    __table_args__ = (UniqueConstraint("server_name", "organization_id", name="uix_name_organization_mcp_server"),)
+
+    server_name: Mapped[str] = mapped_column(doc="The display name of the MCP server")
+    server_type: Mapped[MCPServerType] = mapped_column(
+        String, default=MCPServerType.SSE, doc="The type of the MCP server. Only SSE is supported for remote servers."
+    )
+
+    # sse server
+    server_url: Mapped[Optional[str]] = mapped_column(
+        String, nullable=True, doc="The URL of the server (MCP SSE client will connect to this URL)"
+    )
+
+    # stdio server
+    stdio_config: Mapped[Optional[StdioServerConfig]] = mapped_column(
+        MCPStdioServerConfigColumn, nullable=True, doc="The configuration for the stdio server"
+    )
+
+    metadata_: Mapped[Optional[dict]] = mapped_column(
+        JSON, default=lambda: {}, doc="A dictionary of additional metadata for the MCP server."
+    )
+    # relationships
+    # organization: Mapped["Organization"] = relationship("Organization", back_populates="mcp_server", lazy="selectin")

letta/orm/message.py

@@ -22,6 +22,7 @@ class Message(SqlalchemyBase, OrganizationMixin, AgentMixin):
         Index("ix_messages_agent_created_at", "agent_id", "created_at"),
         Index("ix_messages_created_at", "created_at", "id"),
         Index("ix_messages_agent_sequence", "agent_id", "sequence_id"),
+        Index("ix_messages_org_agent", "organization_id", "agent_id"),
     )
     __pydantic_model__ = PydanticMessage