letta-nightly 0.11.6.dev20250903104037__py3-none-any.whl → 0.11.7.dev20250904104046__py3-none-any.whl

letta/llm_api/openai.py

@@ -21,11 +21,15 @@ from letta.local_llm.utils import num_tokens_from_functions, num_tokens_from_mes
 from letta.log import get_logger
 from letta.otel.tracing import log_event
 from letta.schemas.llm_config import LLMConfig
-from letta.schemas.message import Message as _Message
-from letta.schemas.message import MessageRole as _MessageRole
-from letta.schemas.openai.chat_completion_request import ChatCompletionRequest
-from letta.schemas.openai.chat_completion_request import FunctionCall as ToolFunctionChoiceFunctionCall
-from letta.schemas.openai.chat_completion_request import FunctionSchema, Tool, ToolFunctionChoice, cast_message_to_subtype
+from letta.schemas.message import Message as PydanticMessage, MessageRole as _MessageRole
+from letta.schemas.openai.chat_completion_request import (
+    ChatCompletionRequest,
+    FunctionCall as ToolFunctionChoiceFunctionCall,
+    FunctionSchema,
+    Tool,
+    ToolFunctionChoice,
+    cast_message_to_subtype,
+)
 from letta.schemas.openai.chat_completion_response import (
     ChatCompletionChunkResponse,
     ChatCompletionResponse,
@@ -173,7 +177,7 @@ async def openai_get_model_list_async(
 
 def build_openai_chat_completions_request(
     llm_config: LLMConfig,
-    messages: List[_Message],
+    messages: List[PydanticMessage],
     user_id: Optional[str],
     functions: Optional[list],
     function_call: Optional[str],
@@ -197,13 +201,12 @@ def build_openai_chat_completions_request(
     use_developer_message = accepts_developer_role(llm_config.model)
 
     openai_message_list = [
-        cast_message_to_subtype(
-            m.to_openai_dict(
-                put_inner_thoughts_in_kwargs=llm_config.put_inner_thoughts_in_kwargs,
-                use_developer_message=use_developer_message,
-            )
+        cast_message_to_subtype(m)
+        for m in PydanticMessage.to_openai_dicts_from_list(
+            messages,
+            put_inner_thoughts_in_kwargs=llm_config.put_inner_thoughts_in_kwargs,
+            use_developer_message=use_developer_message,
         )
-        for m in messages
     ]
 
     if llm_config.model:
@@ -322,7 +325,7 @@ def openai_chat_completions_process_stream(
 
     # Create a dummy Message object to get an ID and date
     # TODO(sarah): add message ID generation function
-    dummy_message = _Message(
+    dummy_message = PydanticMessage(
         role=_MessageRole.assistant,
         content=[],
         agent_id="",

letta/llm_api/openai_client.py

@@ -29,11 +29,14 @@ from letta.schemas.embedding_config import EmbeddingConfig
 from letta.schemas.letta_message_content import MessageContentType
 from letta.schemas.llm_config import LLMConfig
 from letta.schemas.message import Message as PydanticMessage
-from letta.schemas.openai.chat_completion_request import ChatCompletionRequest
-from letta.schemas.openai.chat_completion_request import FunctionCall as ToolFunctionChoiceFunctionCall
-from letta.schemas.openai.chat_completion_request import FunctionSchema
-from letta.schemas.openai.chat_completion_request import Tool as OpenAITool
-from letta.schemas.openai.chat_completion_request import ToolFunctionChoice, cast_message_to_subtype
+from letta.schemas.openai.chat_completion_request import (
+    ChatCompletionRequest,
+    FunctionCall as ToolFunctionChoiceFunctionCall,
+    FunctionSchema,
+    Tool as OpenAITool,
+    ToolFunctionChoice,
+    cast_message_to_subtype,
+)
 from letta.schemas.openai.chat_completion_response import ChatCompletionResponse
 from letta.settings import model_settings
 
@@ -44,7 +47,7 @@ def is_openai_reasoning_model(model: str) -> bool:
     """Utility function to check if the model is a 'reasoner'"""
 
     # NOTE: needs to be updated with new model releases
-    is_reasoning = model.startswith("o1") or model.startswith("o3") or model.startswith("o4")
+    is_reasoning = model.startswith("o1") or model.startswith("o3") or model.startswith("o4") or model.startswith("gpt-5")
     return is_reasoning
 
 
@@ -176,13 +179,12 @@ class OpenAIClient(LLMClientBase):
         use_developer_message = accepts_developer_role(llm_config.model)
 
         openai_message_list = [
-            cast_message_to_subtype(
-                m.to_openai_dict(
-                    put_inner_thoughts_in_kwargs=llm_config.put_inner_thoughts_in_kwargs,
-                    use_developer_message=use_developer_message,
-                )
+            cast_message_to_subtype(m)
+            for m in PydanticMessage.to_openai_dicts_from_list(
+                messages,
+                put_inner_thoughts_in_kwargs=llm_config.put_inner_thoughts_in_kwargs,
+                use_developer_message=use_developer_message,
             )
-            for m in messages
         ]
 
         if llm_config.model:
@@ -219,6 +221,10 @@ class OpenAIClient(LLMClientBase):
         if supports_verbosity_control(model) and llm_config.verbosity:
             data.verbosity = llm_config.verbosity
 
+        # Add reasoning effort control for reasoning models
+        if is_openai_reasoning_model(model) and llm_config.reasoning_effort:
+            data.reasoning_effort = llm_config.reasoning_effort
+
         if llm_config.frequency_penalty is not None:
             data.frequency_penalty = llm_config.frequency_penalty
 
@@ -357,10 +363,19 @@ class OpenAIClient(LLMClientBase):
         if isinstance(e, openai.BadRequestError):
             logger.warning(f"[OpenAI] Bad request (400): {str(e)}")
             # 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(...)
-            # TODO: This is a super soft check. Not sure if we can do better, needs more investigation.
-            if "This model's maximum context length is" in str(e):
+            # Check for context_length_exceeded error code in the error body
+            error_code = None
+            if e.body and isinstance(e.body, dict):
+                error_details = e.body.get("error", {})
+                if isinstance(error_details, dict):
+                    error_code = error_details.get("code")
+
+            # Check both the error code and message content for context length issues
+            if (
+                error_code == "context_length_exceeded"
+                or "This model's maximum context length is" in str(e)
+                or "Input tokens exceed the configured limit" in str(e)
+            ):
                 return ContextWindowExceededError(
                     message=f"Bad request to OpenAI (context window exceeded): {str(e)}",
                 )

letta/llm_api/together_client.py

@@ -12,7 +12,6 @@ from letta.settings import model_settings
 
 
 class TogetherClient(OpenAIClient):
-
     def requires_auto_tool_choice(self, llm_config: LLMConfig) -> bool:
         return True
 

letta/llm_api/xai_client.py

@@ -14,7 +14,6 @@ from letta.settings import model_settings
 
 
 class XAIClient(OpenAIClient):
-
     def requires_auto_tool_choice(self, llm_config: LLMConfig) -> bool:
         return False
 

letta/local_llm/chat_completion_proxy.py

@@ -22,6 +22,7 @@ from letta.local_llm.webui.api import get_webui_completion
 from letta.local_llm.webui.legacy_api import get_webui_completion as get_webui_completion_legacy
 from letta.otel.tracing import log_event
 from letta.prompts.gpt_summarize import SYSTEM as SUMMARIZE_SYSTEM_MESSAGE
+from letta.schemas.message import Message as PydanticMessage
 from letta.schemas.openai.chat_completion_response import ChatCompletionResponse, Choice, Message, ToolCall, UsageStatistics
 from letta.utils import get_tool_call_id
 
@@ -61,7 +62,7 @@ def get_chat_completion(
 
     # TODO: eventually just process Message object
     if not isinstance(messages[0], dict):
-        messages = [m.to_openai_dict() for m in messages]
+        messages = PydanticMessage.to_openai_dicts_from_list(messages)
 
     if function_call is not None and function_call != "auto":
         raise ValueError(f"function_call == {function_call} not supported (auto or None only)")
@@ -205,7 +206,7 @@ def get_chat_completion(
         raise LocalLLMError(f"usage dict in response was missing fields ({usage})")
 
     if usage["prompt_tokens"] is None:
-        printd(f"usage dict was missing prompt_tokens, computing on-the-fly...")
+        printd("usage dict was missing prompt_tokens, computing on-the-fly...")
         usage["prompt_tokens"] = count_tokens(prompt)
 
     # NOTE: we should compute on-the-fly anyways since we might have to correct for errors during JSON parsing
@@ -220,7 +221,7 @@ def get_chat_completion(
 
     # NOTE: this is the token count that matters most
     if usage["total_tokens"] is None:
-        printd(f"usage dict was missing total_tokens, computing on-the-fly...")
+        printd("usage dict was missing total_tokens, computing on-the-fly...")
         usage["total_tokens"] = usage["prompt_tokens"] + usage["completion_tokens"]
 
     # unpack with response.choices[0].message.content
@@ -261,9 +262,9 @@ def generate_grammar_and_documentation(
 ):
     from letta.utils import printd
 
-    assert not (
-        add_inner_thoughts_top_level and add_inner_thoughts_param_level
-    ), "Can only place inner thoughts in one location in the grammar generator"
+    assert not (add_inner_thoughts_top_level and add_inner_thoughts_param_level), (
+        "Can only place inner thoughts in one location in the grammar generator"
+    )
 
     grammar_function_models = []
     # create_dynamic_model_from_function will add inner thoughts to the function parameters if add_inner_thoughts is True.

letta/local_llm/settings/settings.py

@@ -46,7 +46,7 @@ def get_completions_settings(defaults="simple") -> dict:
             with open(settings_file, "r", encoding="utf-8") as file:
                 user_settings = json.load(file)
             if len(user_settings) > 0:
-                printd(f"Updating base settings with the following user settings:\n{json_dumps(user_settings,indent=2)}")
+                printd(f"Updating base settings with the following user settings:\n{json_dumps(user_settings, indent=2)}")
                 settings.update(user_settings)
             else:
                 printd(f"'{settings_file}' was empty, ignoring...")

letta/orm/__init__.py

@@ -22,6 +22,7 @@ from letta.orm.mcp_server import MCPServer
 from letta.orm.message import Message
 from letta.orm.organization import Organization
 from letta.orm.passage import ArchivalPassage, BasePassage, SourcePassage
+from letta.orm.passage_tag import PassageTag
 from letta.orm.prompt import Prompt
 from letta.orm.provider import Provider
 from letta.orm.provider_trace import ProviderTrace

letta/orm/agent.py

@@ -10,11 +10,10 @@ from sqlalchemy.orm import Mapped, mapped_column, relationship
 from letta.orm.block import Block
 from letta.orm.custom_columns import EmbeddingConfigColumn, LLMConfigColumn, ResponseFormatColumn, ToolRulesColumn
 from letta.orm.identity import Identity
-from letta.orm.mixins import OrganizationMixin, ProjectMixin
+from letta.orm.mixins import OrganizationMixin, ProjectMixin, TemplateEntityMixin, TemplateMixin
 from letta.orm.organization import Organization
 from letta.orm.sqlalchemy_base import SqlalchemyBase
-from letta.schemas.agent import AgentState as PydanticAgentState
-from letta.schemas.agent import AgentType, get_prompt_template_for_agent_type
+from letta.schemas.agent import AgentState as PydanticAgentState, AgentType, get_prompt_template_for_agent_type
 from letta.schemas.embedding_config import EmbeddingConfig
 from letta.schemas.llm_config import LLMConfig
 from letta.schemas.memory import Memory
@@ -32,7 +31,7 @@ if TYPE_CHECKING:
     from letta.orm.tool import Tool
 
 
-class Agent(SqlalchemyBase, OrganizationMixin, ProjectMixin, AsyncAttrs):
+class Agent(SqlalchemyBase, OrganizationMixin, ProjectMixin, TemplateEntityMixin, TemplateMixin, AsyncAttrs):
     __tablename__ = "agents"
     __pydantic_model__ = PydanticAgentState
     __table_args__ = (Index("ix_agents_created_at", "created_at", "id"),)
@@ -68,8 +67,6 @@ class Agent(SqlalchemyBase, OrganizationMixin, ProjectMixin, AsyncAttrs):
     embedding_config: Mapped[Optional[EmbeddingConfig]] = mapped_column(
         EmbeddingConfigColumn, doc="the embedding configuration object for this agent."
     )
-    template_id: Mapped[Optional[str]] = mapped_column(String, nullable=True, doc="The id of the template the agent belongs to.")
-    base_template_id: Mapped[Optional[str]] = mapped_column(String, nullable=True, doc="The base template id of the agent.")
 
     # Tool rules
     tool_rules: Mapped[Optional[List[ToolRule]]] = mapped_column(ToolRulesColumn, doc="the tool rules for this agent.")
@@ -103,6 +100,7 @@ class Agent(SqlalchemyBase, OrganizationMixin, ProjectMixin, AsyncAttrs):
 
     # indexing controls
     hidden: Mapped[Optional[bool]] = mapped_column(Boolean, nullable=True, default=None, doc="If set to True, the agent will be hidden.")
+    _vector_db_namespace: Mapped[Optional[str]] = mapped_column(String, nullable=True, doc="Private field for vector database namespace")
 
     # relationships
     organization: Mapped["Organization"] = relationship("Organization", back_populates="agents", lazy="raise")
@@ -208,6 +206,8 @@ class Agent(SqlalchemyBase, OrganizationMixin, ProjectMixin, AsyncAttrs):
             "project_id": self.project_id,
             "template_id": self.template_id,
             "base_template_id": self.base_template_id,
+            "deployment_id": self.deployment_id,
+            "entity_id": self.entity_id,
             "tool_rules": self.tool_rules,
             "message_buffer_autoclear": self.message_buffer_autoclear,
             "created_by_id": self.created_by_id,
@@ -296,6 +296,8 @@ class Agent(SqlalchemyBase, OrganizationMixin, ProjectMixin, AsyncAttrs):
             "project_id": self.project_id,
             "template_id": self.template_id,
             "base_template_id": self.base_template_id,
+            "deployment_id": self.deployment_id,
+            "entity_id": self.entity_id,
             "tool_rules": self.tool_rules,
             "message_buffer_autoclear": self.message_buffer_autoclear,
             "created_by_id": self.created_by_id,

letta/orm/archive.py

@@ -2,12 +2,13 @@ import uuid
 from datetime import datetime, timezone
 from typing import TYPE_CHECKING, List, Optional
 
-from sqlalchemy import JSON, Index, String
+from sqlalchemy import JSON, Enum, Index, String
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 
 from letta.orm.mixins import OrganizationMixin
 from letta.orm.sqlalchemy_base import SqlalchemyBase
 from letta.schemas.archive import Archive as PydanticArchive
+from letta.schemas.enums import VectorDBProvider
 from letta.settings import DatabaseChoice, settings
 
 if TYPE_CHECKING:
@@ -38,7 +39,14 @@ class Archive(SqlalchemyBase, OrganizationMixin):
     # archive-specific fields
     name: Mapped[str] = mapped_column(String, nullable=False, doc="The name of the archive")
     description: Mapped[Optional[str]] = mapped_column(String, nullable=True, doc="A description of the archive")
+    vector_db_provider: Mapped[VectorDBProvider] = mapped_column(
+        Enum(VectorDBProvider),
+        nullable=False,
+        default=VectorDBProvider.NATIVE,
+        doc="The vector database provider used for this archive's passages",
+    )
     metadata_: Mapped[Optional[dict]] = mapped_column(JSON, nullable=True, doc="Additional metadata for the archive")
+    _vector_db_namespace: Mapped[Optional[str]] = mapped_column(String, nullable=True, doc="Private field for vector database namespace")
 
     # relationships
     archives_agents: Mapped[List["ArchivesAgents"]] = relationship(

letta/orm/block.py

@@ -6,17 +6,16 @@ from sqlalchemy.orm import Mapped, attributes, declared_attr, mapped_column, rel
 from letta.constants import CORE_MEMORY_BLOCK_CHAR_LIMIT
 from letta.orm.block_history import BlockHistory
 from letta.orm.blocks_agents import BlocksAgents
-from letta.orm.mixins import OrganizationMixin, ProjectMixin
+from letta.orm.mixins import OrganizationMixin, ProjectMixin, TemplateEntityMixin, TemplateMixin
 from letta.orm.sqlalchemy_base import SqlalchemyBase
-from letta.schemas.block import Block as PydanticBlock
-from letta.schemas.block import Human, Persona
+from letta.schemas.block import Block as PydanticBlock, Human, Persona
 
 if TYPE_CHECKING:
     from letta.orm import Organization
     from letta.orm.identity import Identity
 
 
-class Block(OrganizationMixin, SqlalchemyBase, ProjectMixin):
+class Block(OrganizationMixin, SqlalchemyBase, ProjectMixin, TemplateEntityMixin, TemplateMixin):
     """Blocks are sections of the LLM context, representing a specific part of the total Memory"""
 
     __tablename__ = "block"

letta/orm/block_history.py

@@ -38,7 +38,9 @@ class BlockHistory(OrganizationMixin, SqlalchemyBase):
 
     # Relationships
     block_id: Mapped[str] = mapped_column(
-        String, ForeignKey("block.id", ondelete="CASCADE"), nullable=False  # History deleted if Block is deleted
+        String,
+        ForeignKey("block.id", ondelete="CASCADE"),
+        nullable=False,  # History deleted if Block is deleted
     )
 
     sequence_number: Mapped[int] = mapped_column(

letta/orm/group.py

@@ -4,13 +4,12 @@ from typing import List, Optional
 from sqlalchemy import JSON, ForeignKey, String
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 
-from letta.orm.mixins import OrganizationMixin, ProjectMixin
+from letta.orm.mixins import OrganizationMixin, ProjectMixin, TemplateMixin
 from letta.orm.sqlalchemy_base import SqlalchemyBase
 from letta.schemas.group import Group as PydanticGroup
 
 
-class Group(SqlalchemyBase, OrganizationMixin, ProjectMixin):
-
+class Group(SqlalchemyBase, OrganizationMixin, ProjectMixin, TemplateMixin):
     __tablename__ = "groups"
     __pydantic_model__ = PydanticGroup
 

letta/orm/identity.py

@@ -7,8 +7,7 @@ from sqlalchemy.orm import Mapped, mapped_column, relationship
 
 from letta.orm.mixins import OrganizationMixin, ProjectMixin
 from letta.orm.sqlalchemy_base import SqlalchemyBase
-from letta.schemas.identity import Identity as PydanticIdentity
-from letta.schemas.identity import IdentityProperty
+from letta.schemas.identity import Identity as PydanticIdentity, IdentityProperty
 
 
 class Identity(SqlalchemyBase, OrganizationMixin, ProjectMixin):

letta/orm/job.py

@@ -7,8 +7,7 @@ from sqlalchemy.orm import Mapped, mapped_column, relationship
 from letta.orm.mixins import UserMixin
 from letta.orm.sqlalchemy_base import SqlalchemyBase
 from letta.schemas.enums import JobStatus, JobType
-from letta.schemas.job import Job as PydanticJob
-from letta.schemas.job import LettaRequestConfig
+from letta.schemas.job import Job as PydanticJob, LettaRequestConfig
 
 if TYPE_CHECKING:
     from letta.orm.job_messages import JobMessage

letta/orm/llm_batch_items.py

@@ -9,8 +9,7 @@ from letta.orm.custom_columns import AgentStepStateColumn, BatchRequestResultCol
 from letta.orm.mixins import AgentMixin, OrganizationMixin
 from letta.orm.sqlalchemy_base import SqlalchemyBase
 from letta.schemas.enums import AgentStepStatus, JobStatus
-from letta.schemas.llm_batch_job import AgentStepState
-from letta.schemas.llm_batch_job import LLMBatchItem as PydanticLLMBatchItem
+from letta.schemas.llm_batch_job import AgentStepState, LLMBatchItem as PydanticLLMBatchItem
 from letta.schemas.llm_config import LLMConfig
 
 

letta/orm/message.py

@@ -7,10 +7,8 @@ from sqlalchemy.orm import Mapped, Session, mapped_column, relationship
 from letta.orm.custom_columns import MessageContentColumn, ToolCallColumn, ToolReturnColumn
 from letta.orm.mixins import AgentMixin, OrganizationMixin
 from letta.orm.sqlalchemy_base import SqlalchemyBase
-from letta.schemas.letta_message_content import MessageContent
-from letta.schemas.letta_message_content import TextContent as PydanticTextContent
-from letta.schemas.message import Message as PydanticMessage
-from letta.schemas.message import ToolReturn
+from letta.schemas.letta_message_content import MessageContent, TextContent as PydanticTextContent
+from letta.schemas.message import Message as PydanticMessage, ToolReturn
 from letta.settings import DatabaseChoice, settings
 
 
@@ -52,6 +50,12 @@ class Message(SqlalchemyBase, OrganizationMixin, AgentMixin):
     is_err: Mapped[Optional[bool]] = mapped_column(
         nullable=True, doc="Whether this message is part of an error step. Used only for debugging purposes."
     )
+    approval_request_id: Mapped[Optional[str]] = mapped_column(
+        nullable=True,
+        doc="The id of the approval request if this message is associated with a tool call request.",
+    )
+    approve: Mapped[Optional[bool]] = mapped_column(nullable=True, doc="Whether tool call is approved.")
+    denial_reason: Mapped[Optional[str]] = mapped_column(nullable=True, doc="The reason the tool call request was denied.")
 
     # Monotonically increasing sequence for efficient/correct listing
     sequence_id: Mapped[int] = mapped_column(

letta/orm/mixins.py

@@ -78,3 +78,21 @@ class ArchiveMixin(Base):
     __abstract__ = True
 
     archive_id: Mapped[str] = mapped_column(String, ForeignKey("archives.id", ondelete="CASCADE"))
+
+
+class TemplateMixin(Base):
+    """TemplateMixin for models that belong to a template."""
+
+    __abstract__ = True
+
+    base_template_id: Mapped[str] = mapped_column(nullable=True, doc="The id of the base template.")
+    template_id: Mapped[str] = mapped_column(nullable=True, doc="The id of the template.")
+    deployment_id: Mapped[str] = mapped_column(nullable=True, doc="The id of the deployment.")
+
+
+class TemplateEntityMixin(Base):
+    """Mixin for models that belong to an entity (only used for templates)."""
+
+    __abstract__ = True
+
+    entity_id: Mapped[str] = mapped_column(nullable=True, doc="The id of the entity within the template.")

letta/orm/organization.py

@@ -16,6 +16,7 @@ if TYPE_CHECKING:
     from letta.orm.llm_batch_job import LLMBatchJob
     from letta.orm.message import Message
     from letta.orm.passage import ArchivalPassage, SourcePassage
+    from letta.orm.passage_tag import PassageTag
     from letta.orm.provider import Provider
     from letta.orm.sandbox_config import AgentEnvironmentVariable, SandboxConfig, SandboxEnvironmentVariable
     from letta.orm.tool import Tool
@@ -56,6 +57,7 @@ class Organization(SqlalchemyBase):
     archival_passages: Mapped[List["ArchivalPassage"]] = relationship(
         "ArchivalPassage", back_populates="organization", cascade="all, delete-orphan"
     )
+    passage_tags: Mapped[List["PassageTag"]] = relationship("PassageTag", back_populates="organization", cascade="all, delete-orphan")
     archives: Mapped[List["Archive"]] = relationship("Archive", back_populates="organization", cascade="all, delete-orphan")
     providers: Mapped[List["Provider"]] = relationship("Provider", back_populates="organization", cascade="all, delete-orphan")
     identities: Mapped[List["Identity"]] = relationship("Identity", back_populates="organization", cascade="all, delete-orphan")

letta/orm/passage.py

@@ -1,4 +1,4 @@
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, List, Optional
 
 from sqlalchemy import JSON, Column, Index
 from sqlalchemy.orm import Mapped, declared_attr, mapped_column, relationship
@@ -27,6 +27,8 @@ class BasePassage(SqlalchemyBase, OrganizationMixin):
     text: Mapped[str] = mapped_column(doc="Passage text content")
     embedding_config: Mapped[dict] = mapped_column(EmbeddingConfigColumn, doc="Embedding configuration")
     metadata_: Mapped[dict] = mapped_column(JSON, doc="Additional metadata")
+    # dual storage: json column for fast retrieval, junction table for efficient queries
+    tags: Mapped[Optional[List[str]]] = mapped_column(JSON, nullable=True, doc="Tags associated with this passage")
 
     # Vector embedding field based on database type
     if settings.database_engine is DatabaseChoice.POSTGRES:
@@ -75,6 +77,11 @@ class ArchivalPassage(BasePassage, ArchiveMixin):
 
     __tablename__ = "archival_passages"
 
+    # junction table for efficient tag queries (complements json column above)
+    passage_tags: Mapped[List["PassageTag"]] = relationship(
+        "PassageTag", back_populates="passage", cascade="all, delete-orphan", lazy="noload"
+    )
+
     @declared_attr
     def organization(cls) -> Mapped["Organization"]:
         return relationship("Organization", back_populates="archival_passages", lazy="selectin")

letta/orm/passage_tag.py

@@ -0,0 +1,55 @@
+from typing import TYPE_CHECKING
+
+from sqlalchemy import ForeignKey, Index, String, UniqueConstraint
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from letta.orm.mixins import OrganizationMixin
+from letta.orm.sqlalchemy_base import SqlalchemyBase
+
+if TYPE_CHECKING:
+    from letta.orm.organization import Organization
+    from letta.orm.passage import ArchivalPassage
+
+
+class PassageTag(SqlalchemyBase, OrganizationMixin):
+    """Junction table for tags associated with passages.
+
+    Design: dual storage approach where tags are stored both in:
+    1. JSON column in passages table (fast retrieval with passage data)
+    2. This junction table (efficient DISTINCT/COUNT queries and filtering)
+    """
+
+    __tablename__ = "passage_tags"
+
+    __table_args__ = (
+        # ensure uniqueness of tag per passage
+        UniqueConstraint("passage_id", "tag", name="uq_passage_tag"),
+        # indexes for efficient queries
+        Index("ix_passage_tags_archive_id", "archive_id"),
+        Index("ix_passage_tags_tag", "tag"),
+        Index("ix_passage_tags_archive_tag", "archive_id", "tag"),
+        Index("ix_passage_tags_org_archive", "organization_id", "archive_id"),
+    )
+
+    # primary key
+    id: Mapped[str] = mapped_column(String, primary_key=True, doc="Unique identifier for the tag entry")
+
+    # tag value
+    tag: Mapped[str] = mapped_column(String, nullable=False, doc="The tag value")
+
+    # foreign keys
+    passage_id: Mapped[str] = mapped_column(
+        String, ForeignKey("archival_passages.id", ondelete="CASCADE"), nullable=False, doc="ID of the passage this tag belongs to"
+    )
+
+    archive_id: Mapped[str] = mapped_column(
+        String,
+        ForeignKey("archives.id", ondelete="CASCADE"),
+        nullable=False,
+        doc="ID of the archive this passage belongs to (denormalized for efficient queries)",
+    )
+
+    # relationships
+    passage: Mapped["ArchivalPassage"] = relationship("ArchivalPassage", back_populates="passage_tags", lazy="noload")
+
+    organization: Mapped["Organization"] = relationship("Organization", back_populates="passage_tags", lazy="selectin")

letta/orm/sandbox_config.py

@@ -1,9 +1,7 @@
 import uuid
 from typing import TYPE_CHECKING, Dict, List, Optional
 
-from sqlalchemy import JSON
-from sqlalchemy import Enum as SqlEnum
-from sqlalchemy import Index, String, UniqueConstraint
+from sqlalchemy import JSON, Enum as SqlEnum, Index, String, UniqueConstraint
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 
 from letta.orm.mixins import AgentMixin, OrganizationMixin, SandboxConfigMixin

letta/orm/step.py

@@ -7,7 +7,6 @@ from sqlalchemy.orm import Mapped, mapped_column, relationship
 from letta.orm.mixins import ProjectMixin
 from letta.orm.sqlalchemy_base import SqlalchemyBase
 from letta.schemas.enums import StepStatus
-from letta.schemas.letta_stop_reason import StopReasonType
 from letta.schemas.step import Step as PydanticStep
 
 if TYPE_CHECKING:
@@ -51,7 +50,7 @@ class Step(SqlalchemyBase, ProjectMixin):
     prompt_tokens: Mapped[int] = mapped_column(default=0, doc="Number of tokens in the prompt")
     total_tokens: Mapped[int] = mapped_column(default=0, doc="Total number of tokens processed by the agent")
     completion_tokens_details: Mapped[Optional[Dict]] = mapped_column(JSON, nullable=True, doc="metadata for the agent.")
-    stop_reason: Mapped[Optional[StopReasonType]] = mapped_column(None, nullable=True, doc="The stop reason associated with this step.")
+    stop_reason: Mapped[Optional[str]] = mapped_column(None, nullable=True, doc="The stop reason associated with this step.")
     tags: Mapped[Optional[List]] = mapped_column(JSON, doc="Metadata tags.")
     tid: Mapped[Optional[str]] = mapped_column(None, nullable=True, doc="Transaction ID that processed the step.")
     trace_id: Mapped[Optional[str]] = mapped_column(None, nullable=True, doc="The trace id of the agent step.")

letta/orm/tool.py

@@ -49,6 +49,7 @@ class Tool(SqlalchemyBase, OrganizationMixin):
         JSON, nullable=True, doc="Optional list of pip packages required by this tool."
     )
     npm_requirements: Mapped[list | None] = mapped_column(JSON, doc="Optional list of npm packages required by this tool.")
+    default_requires_approval: Mapped[bool] = mapped_column(nullable=True, doc="Whether or not to require approval.")
     metadata_: Mapped[Optional[dict]] = mapped_column(JSON, default=lambda: {}, doc="A dictionary of additional metadata for the tool.")
     # relationships
     organization: Mapped["Organization"] = relationship("Organization", back_populates="tools", lazy="selectin")

letta/otel/resource.py

@@ -1,16 +1,16 @@
-import os
 import sys
 import uuid
 
 from opentelemetry.sdk.resources import Resource
 
 from letta import __version__ as letta_version
+from letta.settings import settings
 
 _resources = {}
 
 
 def get_resource(service_name: str) -> Resource:
-    _env = os.getenv("LETTA_ENVIRONMENT")
+    _env = settings.environment
     if service_name not in _resources:
         resource_dict = {
             "service.name": service_name,

letta/plugins/plugins.py

@@ -37,7 +37,7 @@ def get_plugin(plugin_type: str):
             return plugin
         elif type(plugin).__name__ == "class":
             if plugin_register["protocol"] and not isinstance(plugin, type(plugin_register["protocol"])):
-                raise TypeError(f'{plugin} does not implement {type(plugin_register["protocol"]).__name__}')
+                raise TypeError(f"{plugin} does not implement {type(plugin_register['protocol']).__name__}")
             return plugin()
     raise TypeError("Unknown plugin type")