letta-nightly 0.11.7.dev20250916104104__py3-none-any.whl → 0.11.7.dev20250917104122__py3-none-any.whl

letta/__init__.py

@@ -10,8 +10,16 @@ except PackageNotFoundError:
 if os.environ.get("LETTA_VERSION"):
     __version__ = os.environ["LETTA_VERSION"]
 
-# Import sqlite_functions early to ensure event handlers are registered
-from letta.orm import sqlite_functions
+# Import sqlite_functions early to ensure event handlers are registered (only for SQLite)
+# This is only needed for the server, not for client usage
+try:
+    from letta.settings import DatabaseChoice, settings
+
+    if settings.database_engine == DatabaseChoice.SQLITE:
+        from letta.orm import sqlite_functions
+except ImportError:
+    # If sqlite_vec is not installed, it's fine for client usage
+    pass
 
 # # imports for easier access
 from letta.schemas.agent import AgentState

letta/adapters/letta_llm_request_adapter.py

@@ -106,7 +106,6 @@ class LettaLLMRequestAdapter(LettaLLMAdapter):
                     request_json=self.request_data,
                     response_json=self.response_data,
                     step_id=step_id,  # Use original step_id for telemetry
-                    organization_id=actor.organization_id,
                 ),
             ),
             label="create_provider_trace",

letta/adapters/letta_llm_stream_adapter.py

@@ -164,7 +164,6 @@ class LettaLLMStreamAdapter(LettaLLMAdapter):
                         },
                     },
                     step_id=step_id,  # Use original step_id for telemetry
-                    organization_id=actor.organization_id,
                 ),
             ),
             label="create_provider_trace",

letta/agent.py

@@ -1628,7 +1628,7 @@ class Agent(BaseAgent):
                 action_name = generate_composio_action_from_func_name(target_letta_tool.name)
                 # Get entity ID from the agent_state
                 entity_id = None
-                for env_var in self.agent_state.tool_exec_environment_variables:
+                for env_var in self.agent_state.secrets:
                     if env_var.key == COMPOSIO_ENTITY_ENV_VAR_KEY:
                         entity_id = env_var.value
                 # Get composio_api_key

letta/agents/letta_agent.py

@@ -405,7 +405,6 @@ class LettaAgent(BaseAgent):
                                 request_json=request_data,
                                 response_json=response_data,
                                 step_id=step_id,  # Use original step_id for telemetry
-                                organization_id=self.actor.organization_id,
                             ),
                         )
                         step_progression = StepProgression.LOGGED_TRACE
@@ -751,7 +750,6 @@ class LettaAgent(BaseAgent):
                                 request_json=request_data,
                                 response_json=response_data,
                                 step_id=step_id,  # Use original step_id for telemetry
-                                organization_id=self.actor.organization_id,
                             ),
                         )
                         step_progression = StepProgression.LOGGED_TRACE
@@ -1173,7 +1171,6 @@ class LettaAgent(BaseAgent):
                                     },
                                 },
                                 step_id=step_id,  # Use original step_id for telemetry
-                                organization_id=self.actor.organization_id,
                             ),
                         )
                         step_progression = StepProgression.LOGGED_TRACE
@@ -1877,7 +1874,7 @@ class LettaAgent(BaseAgent):
             start_time = get_utc_timestamp_ns()
             agent_step_span.add_event(name="tool_execution_started")
 
-        sandbox_env_vars = {var.key: var.value for var in agent_state.tool_exec_environment_variables}
+        sandbox_env_vars = {var.key: var.value for var in agent_state.secrets}
         tool_execution_manager = ToolExecutionManager(
             agent_state=agent_state,
             message_manager=self.message_manager,

letta/agents/letta_agent_v2.py

@@ -1106,7 +1106,7 @@ class LettaAgentV2(BaseAgentV2):
             start_time = get_utc_timestamp_ns()
             agent_step_span.add_event(name="tool_execution_started")
 
-        sandbox_env_vars = {var.key: var.value for var in agent_state.tool_exec_environment_variables}
+        sandbox_env_vars = {var.key: var.value for var in agent_state.secrets}
         tool_execution_manager = ToolExecutionManager(
             agent_state=agent_state,
             message_manager=self.message_manager,
@@ -1226,6 +1226,7 @@ class LettaAgentV2(BaseAgentV2):
                     new_status=JobStatus.failed if is_error else JobStatus.completed,
                     actor=self.actor,
                     metadata=job_update_metadata,
+                    stop_reason=self.stop_reason.stop_reason if self.stop_reason else StopReasonType.error,
                 )
         if request_span:
             request_span.end()

letta/agents/voice_agent.py

@@ -441,7 +441,7 @@ class VoiceAgent(BaseAgent):
             )
 
         # Use ToolExecutionManager for modern tool execution
-        sandbox_env_vars = {var.key: var.value for var in agent_state.tool_exec_environment_variables}
+        sandbox_env_vars = {var.key: var.value for var in agent_state.secrets}
         tool_execution_manager = ToolExecutionManager(
             agent_state=agent_state,
             message_manager=self.message_manager,

letta/helpers/converters.py

@@ -44,8 +44,14 @@ from letta.schemas.tool_rule import (
 )
 from letta.settings import DatabaseChoice, settings
 
-if settings.database_engine == DatabaseChoice.SQLITE:
-    import sqlite_vec
+# Only import sqlite_vec if we're actually using SQLite database
+# This is a runtime dependency only needed for SQLite vector operations
+try:
+    if settings.database_engine == DatabaseChoice.SQLITE:
+        import sqlite_vec
+except ImportError:
+    # If sqlite_vec is not installed, it's fine for client usage
+    pass
 # --------------------------
 # LLMConfig Serialization
 # --------------------------

letta/helpers/crypto_utils.py

@@ -0,0 +1,144 @@
+import base64
+import os
+from typing import Optional
+
+from cryptography.hazmat.backends import default_backend
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC
+
+from letta.settings import settings
+
+
+class CryptoUtils:
+    """Utility class for AES-256-GCM encryption/decryption of sensitive data."""
+
+    # AES-256 requires 32 bytes key
+    KEY_SIZE = 32
+    # GCM standard IV size is 12 bytes (96 bits)
+    IV_SIZE = 12
+    # GCM tag size is 16 bytes (128 bits)
+    TAG_SIZE = 16
+    # Salt size for key derivation
+    SALT_SIZE = 16
+
+    @classmethod
+    def _derive_key(cls, master_key: str, salt: bytes) -> bytes:
+        """Derive an AES key from the master key using PBKDF2."""
+        kdf = PBKDF2HMAC(algorithm=hashes.SHA256(), length=cls.KEY_SIZE, salt=salt, iterations=100000, backend=default_backend())
+        return kdf.derive(master_key.encode())
+
+    @classmethod
+    def encrypt(cls, plaintext: str, master_key: Optional[str] = None) -> str:
+        """
+        Encrypt a string using AES-256-GCM.
+
+        Args:
+            plaintext: The string to encrypt
+            master_key: Optional master key (defaults to settings.encryption_key)
+
+        Returns:
+            Base64 encoded string containing: salt + iv + ciphertext + tag
+
+        Raises:
+            ValueError: If no encryption key is configured
+        """
+        if master_key is None:
+            master_key = settings.encryption_key
+
+        if not master_key:
+            raise ValueError("No encryption key configured. Set LETTA_ENCRYPTION_KEY environment variable.")
+
+        # Generate random salt and IV
+        salt = os.urandom(cls.SALT_SIZE)
+        iv = os.urandom(cls.IV_SIZE)
+
+        # Derive key from master key
+        key = cls._derive_key(master_key, salt)
+
+        # Create cipher
+        cipher = Cipher(algorithms.AES(key), modes.GCM(iv), backend=default_backend())
+        encryptor = cipher.encryptor()
+
+        # Encrypt the plaintext
+        ciphertext = encryptor.update(plaintext.encode()) + encryptor.finalize()
+
+        # Get the authentication tag
+        tag = encryptor.tag
+
+        # Combine salt + iv + ciphertext + tag
+        encrypted_data = salt + iv + ciphertext + tag
+
+        # Return as base64 encoded string
+        return base64.b64encode(encrypted_data).decode("utf-8")
+
+    @classmethod
+    def decrypt(cls, encrypted: str, master_key: Optional[str] = None) -> str:
+        """
+        Decrypt a string that was encrypted using AES-256-GCM.
+
+        Args:
+            encrypted: Base64 encoded encrypted string
+            master_key: Optional master key (defaults to settings.encryption_key)
+
+        Returns:
+            The decrypted plaintext string
+
+        Raises:
+            ValueError: If no encryption key is configured or decryption fails
+        """
+        if master_key is None:
+            master_key = settings.encryption_key
+
+        if not master_key:
+            raise ValueError("No encryption key configured. Set LETTA_ENCRYPTION_KEY environment variable.")
+
+        try:
+            # Decode from base64
+            encrypted_data = base64.b64decode(encrypted)
+
+            # Extract components
+            salt = encrypted_data[: cls.SALT_SIZE]
+            iv = encrypted_data[cls.SALT_SIZE : cls.SALT_SIZE + cls.IV_SIZE]
+            ciphertext = encrypted_data[cls.SALT_SIZE + cls.IV_SIZE : -cls.TAG_SIZE]
+            tag = encrypted_data[-cls.TAG_SIZE :]
+
+            # Derive key from master key
+            key = cls._derive_key(master_key, salt)
+
+            # Create cipher
+            cipher = Cipher(algorithms.AES(key), modes.GCM(iv, tag), backend=default_backend())
+            decryptor = cipher.decryptor()
+
+            # Decrypt the ciphertext
+            plaintext = decryptor.update(ciphertext) + decryptor.finalize()
+
+            return plaintext.decode("utf-8")
+
+        except Exception as e:
+            raise ValueError(f"Failed to decrypt data: {str(e)}")
+
+    @classmethod
+    def is_encrypted(cls, value: str) -> bool:
+        """
+        Check if a string appears to be encrypted (base64 encoded with correct size).
+
+        This is a heuristic check and may have false positives.
+        """
+        try:
+            decoded = base64.b64decode(value)
+            # Check if length is consistent with our encryption format
+            # Minimum size: salt(16) + iv(12) + tag(16) + at least 1 byte of ciphertext
+            return len(decoded) >= cls.SALT_SIZE + cls.IV_SIZE + cls.TAG_SIZE + 1
+        except Exception:
+            return False
+
+    @classmethod
+    def is_encryption_available(cls) -> bool:
+        """
+        Check if encryption is available (encryption key is configured).
+
+        Returns:
+            True if encryption key is configured, False otherwise
+        """
+        return bool(settings.encryption_key)

letta/llm_api/llm_api_tools.py

@@ -235,7 +235,6 @@ def create(
                 request_json=prepare_openai_payload(data),
                 response_json=response.model_json_schema(),
                 step_id=step_id,
-                organization_id=actor.organization_id,
             ),
         )
 

letta/llm_api/llm_client_base.py

@@ -64,7 +64,6 @@ class LLMClientBase:
                         request_json=request_data,
                         response_json=response_data,
                         step_id=step_id,
-                        organization_id=self.actor.organization_id,
                     ),
                 )
             log_event(name="llm_response_received", attributes=response_data)
@@ -98,7 +97,6 @@ class LLMClientBase:
                         request_json=request_data,
                         response_json=response_data,
                         step_id=step_id,
-                        organization_id=self.actor.organization_id,
                     ),
                 )
 

letta/orm/__init__.py

@@ -18,6 +18,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_oauth import MCPOAuth
 from letta.orm.mcp_server import MCPServer
 from letta.orm.message import Message
 from letta.orm.organization import Organization

letta/orm/agent.py

@@ -233,6 +233,7 @@ class Agent(SqlalchemyBase, OrganizationMixin, ProjectMixin, TemplateEntityMixin
             "identity_ids": [],
             "multi_agent_group": None,
             "tool_exec_environment_variables": [],
+            "secrets": [],
         }
 
         # Optional fields: only included if requested
@@ -253,6 +254,7 @@ class Agent(SqlalchemyBase, OrganizationMixin, ProjectMixin, TemplateEntityMixin
             "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,
+            "secrets": lambda: self.tool_exec_environment_variables,
         }
 
         include_relationships = set(optional_fields.keys() if include_relationships is None else include_relationships)
@@ -324,6 +326,7 @@ class Agent(SqlalchemyBase, OrganizationMixin, ProjectMixin, TemplateEntityMixin
             "identity_ids": [],
             "multi_agent_group": None,
             "tool_exec_environment_variables": [],
+            "secrets": [],
         }
 
         # Initialize include_relationships to an empty set if it's None
@@ -344,7 +347,7 @@ class Agent(SqlalchemyBase, OrganizationMixin, ProjectMixin, TemplateEntityMixin
         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
+            if "tool_exec_environment_variables" in include_relationships or "secrets" in include_relationships
             else empty_list_async()
         )
         file_agents = self.awaitable_attrs.file_agents if "memory" in include_relationships else empty_list_async()
@@ -368,5 +371,6 @@ class Agent(SqlalchemyBase, OrganizationMixin, ProjectMixin, TemplateEntityMixin
         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
+        state["secrets"] = tool_exec_environment_variables
 
         return self.__pydantic_model__(**state)

letta/orm/job.py

@@ -1,13 +1,14 @@
 from datetime import datetime
 from typing import TYPE_CHECKING, List, Optional
 
-from sqlalchemy import JSON, BigInteger, ForeignKey, Index, String
+from sqlalchemy import JSON, BigInteger, Boolean, ForeignKey, Index, String
 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, LettaRequestConfig
+from letta.schemas.letta_stop_reason import StopReasonType
 
 if TYPE_CHECKING:
     from letta.orm.job_messages import JobMessage
@@ -28,6 +29,7 @@ class Job(SqlalchemyBase, UserMixin):
 
     status: Mapped[JobStatus] = mapped_column(String, default=JobStatus.created, doc="The current status of the job.")
     completed_at: Mapped[Optional[datetime]] = mapped_column(nullable=True, doc="The unix timestamp of when the job was completed.")
+    stop_reason: Mapped[Optional[StopReasonType]] = mapped_column(String, nullable=True, doc="The reason why the job was stopped.")
     metadata_: Mapped[Optional[dict]] = mapped_column(JSON, doc="The metadata of the job.")
     job_type: Mapped[JobType] = mapped_column(
         String,

letta/orm/mcp_oauth.py

@@ -38,7 +38,11 @@ class MCPOAuth(SqlalchemyBase, OrganizationMixin, UserMixin):
 
     # Token data
     access_token: Mapped[Optional[str]] = mapped_column(Text, nullable=True, doc="OAuth access token")
+    access_token_enc: Mapped[Optional[str]] = mapped_column(Text, nullable=True, doc="Encrypted OAuth access token")
+
     refresh_token: Mapped[Optional[str]] = mapped_column(Text, nullable=True, doc="OAuth refresh token")
+    refresh_token_enc: Mapped[Optional[str]] = mapped_column(Text, nullable=True, doc="Encrypted OAuth refresh token")
+
     token_type: Mapped[str] = mapped_column(String(50), default="Bearer", doc="Token type")
     expires_at: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True), nullable=True, doc="Token expiry time")
     scope: Mapped[Optional[str]] = mapped_column(Text, nullable=True, doc="OAuth scope")
@@ -46,6 +50,8 @@ class MCPOAuth(SqlalchemyBase, OrganizationMixin, UserMixin):
     # Client configuration
     client_id: Mapped[Optional[str]] = mapped_column(Text, nullable=True, doc="OAuth client ID")
     client_secret: Mapped[Optional[str]] = mapped_column(Text, nullable=True, doc="OAuth client secret")
+    client_secret_enc: Mapped[Optional[str]] = mapped_column(Text, nullable=True, doc="Encrypted OAuth client secret")
+
     redirect_uri: Mapped[Optional[str]] = mapped_column(Text, nullable=True, doc="OAuth redirect URI")
 
     # Session state

letta/orm/mcp_server.py

@@ -1,6 +1,6 @@
 from typing import TYPE_CHECKING, Optional
 
-from sqlalchemy import JSON, String, UniqueConstraint
+from sqlalchemy import JSON, String, Text, UniqueConstraint
 from sqlalchemy.orm import Mapped, mapped_column
 
 from letta.functions.mcp_client.types import StdioServerConfig
@@ -39,9 +39,15 @@ class MCPServer(SqlalchemyBase, OrganizationMixin):
     # access token / api key for MCP servers that require authentication
     token: Mapped[Optional[str]] = mapped_column(String, nullable=True, doc="The access token or api key for the MCP server")
 
+    # encrypted access token or api key for the MCP server
+    token_enc: Mapped[Optional[str]] = mapped_column(Text, nullable=True, doc="Encrypted access token or api key for the MCP server")
+
     # custom headers for authentication (key-value pairs)
     custom_headers: Mapped[Optional[dict]] = mapped_column(JSON, nullable=True, doc="Custom authentication headers as key-value pairs")
 
+    # encrypted custom headers for authentication (key-value pairs)
+    custom_headers_enc: Mapped[Optional[str]] = mapped_column(Text, nullable=True, doc="Encrypted custom authentication headers")
+
     # stdio server
     stdio_config: Mapped[Optional[StdioServerConfig]] = mapped_column(
         MCPStdioServerConfigColumn, nullable=True, doc="The configuration for the stdio server"

letta/orm/sqlalchemy_base.py

@@ -14,7 +14,6 @@ from sqlalchemy.orm.interfaces import ORMOption
 from letta.log import get_logger
 from letta.orm.base import Base, CommonSqlalchemyMetaMixins
 from letta.orm.errors import DatabaseTimeoutError, ForeignKeyConstraintViolationError, NoResultFound, UniqueConstraintViolationError
-from letta.orm.sqlite_functions import adapt_array
 from letta.settings import DatabaseChoice
 
 if TYPE_CHECKING:
@@ -401,6 +400,8 @@ class SqlalchemyBase(CommonSqlalchemyMetaMixins, Base):
                 query = query.order_by(cls.embedding.cosine_distance(query_embedding).asc())
             else:
                 # SQLite with custom vector type
+                from letta.orm.sqlite_functions import adapt_array
+
                 query_embedding_binary = adapt_array(query_embedding)
                 query = query.order_by(
                     func.cosine_distance(cls.embedding, query_embedding_binary).asc(),

letta/schemas/agent.py

@@ -86,6 +86,11 @@ class AgentState(OrmMetadataBase, validate_assignment=True):
     sources: List[Source] = Field(..., description="The sources used by the agent.")
     tags: List[str] = Field(..., description="The tags associated with the agent.")
     tool_exec_environment_variables: List[AgentEnvironmentVariable] = Field(
+        default_factory=list,
+        description="Deprecated: use `secrets` field instead.",
+        deprecated=True,
+    )
+    secrets: List[AgentEnvironmentVariable] = Field(
         default_factory=list, description="The environment variables for tool execution specific to this agent."
     )
     project_id: Optional[str] = Field(None, description="The id of the project the agent belongs to.")
@@ -133,7 +138,7 @@ class AgentState(OrmMetadataBase, validate_assignment=True):
     def get_agent_env_vars_as_dict(self) -> Dict[str, str]:
         # Get environment variables for this agent specifically
         per_agent_env_vars = {}
-        for agent_env_var_obj in self.tool_exec_environment_variables:
+        for agent_env_var_obj in self.secrets:
             per_agent_env_vars[agent_env_var_obj.key] = agent_env_var_obj.value
         return per_agent_env_vars
 
@@ -222,9 +227,8 @@ class CreateAgent(BaseModel, validate_assignment=True):  #
         deprecated=True,
         description="Deprecated: Project should now be passed via the X-Project header instead of in the request body. If using the sdk, this can be done via the new x_project field below.",
     )
-    tool_exec_environment_variables: Optional[Dict[str, str]] = Field(
-        None, description="The environment variables for tool execution specific to this agent."
-    )
+    tool_exec_environment_variables: Optional[Dict[str, str]] = Field(None, description="Deprecated: use `secrets` field instead.")
+    secrets: Optional[Dict[str, str]] = Field(None, description="The environment variables for tool execution specific to this agent.")
     memory_variables: Optional[Dict[str, str]] = Field(None, description="The variables that should be set for the agent.")
     project_id: Optional[str] = Field(None, description="The id of the project the agent belongs to.")
     template_id: Optional[str] = Field(None, description="The id of the template the agent belongs to.")
@@ -328,9 +332,8 @@ class UpdateAgent(BaseModel):
     message_ids: Optional[List[str]] = Field(None, description="The ids of the messages in the agent's in-context memory.")
     description: Optional[str] = Field(None, description="The description of the agent.")
     metadata: Optional[Dict] = Field(None, description="The metadata of the agent.")
-    tool_exec_environment_variables: Optional[Dict[str, str]] = Field(
-        None, description="The environment variables for tool execution specific to this agent."
-    )
+    tool_exec_environment_variables: Optional[Dict[str, str]] = Field(None, description="Deprecated: use `secrets` field instead")
+    secrets: Optional[Dict[str, str]] = Field(None, description="The environment variables for tool execution specific to this agent.")
     project_id: Optional[str] = Field(None, description="The id of the project the agent belongs to.")
     template_id: Optional[str] = Field(None, description="The id of the template the agent belongs to.")
     base_template_id: Optional[str] = Field(None, description="The base template id of the agent.")

letta/schemas/job.py

@@ -8,16 +8,26 @@ from letta.helpers.datetime_helpers import get_utc_time
 from letta.schemas.enums import JobStatus, JobType
 from letta.schemas.letta_base import OrmMetadataBase
 from letta.schemas.letta_message import MessageType
+from letta.schemas.letta_stop_reason import StopReasonType
 
 
 class JobBase(OrmMetadataBase):
     __id_prefix__ = "job"
     status: JobStatus = Field(default=JobStatus.created, description="The status of the job.")
     created_at: datetime = Field(default_factory=get_utc_time, description="The unix timestamp of when the job was created.")
+
+    # completion related
     completed_at: Optional[datetime] = Field(None, description="The unix timestamp of when the job was completed.")
+    stop_reason: Optional[StopReasonType] = Field(None, description="The reason why the job was stopped.")
+
+    # metadata
     metadata: Optional[dict] = Field(None, validation_alias="metadata_", description="The metadata of the job.")
     job_type: JobType = Field(default=JobType.JOB, description="The type of the job.")
 
+    ## TODO: Run-specific fields
+    # background: Optional[bool] = Field(None, description="Whether the job was created in background mode.")
+    # agent_id: Optional[str] = Field(None, description="The agent associated with this job/run.")
+
     callback_url: Optional[str] = Field(None, description="If set, POST to this URL when the job completes.")
     callback_sent_at: Optional[datetime] = Field(None, description="Timestamp when the callback was last attempted.")
     callback_status_code: Optional[int] = Field(None, description="HTTP status code returned by the callback endpoint.")