letta-nightly 0.5.4.dev20241121104201__py3-none-any.whl → 0.5.4.dev20241123104112__py3-none-any.whl

letta/server/server.py

@@ -77,7 +77,9 @@ from letta.schemas.usage import LettaUsageStatistics
 from letta.schemas.user import User
 from letta.services.agents_tags_manager import AgentsTagsManager
 from letta.services.block_manager import BlockManager
+from letta.services.blocks_agents_manager import BlocksAgentsManager
 from letta.services.organization_manager import OrganizationManager
+from letta.services.sandbox_config_manager import SandboxConfigManager
 from letta.services.source_manager import SourceManager
 from letta.services.tool_manager import ToolManager
 from letta.services.user_manager import UserManager
@@ -247,6 +249,8 @@ class SyncServer(Server):
         self.block_manager = BlockManager()
         self.source_manager = SourceManager()
         self.agents_tags_manager = AgentsTagsManager()
+        self.blocks_agents_manager = BlocksAgentsManager()
+        self.sandbox_config_manager = SandboxConfigManager(tool_settings)
 
         # Make default user and org
         if init_with_default_org_and_user:
@@ -328,6 +332,15 @@ class SyncServer(Server):
                 )
             )
 
+    def save_agents(self):
+        """Saves all the agents that are in the in-memory object store"""
+        for agent_d in self.active_agents:
+            try:
+                save_agent(agent_d["agent"], self.ms)
+                logger.info(f"Saved agent {agent_d['agent_id']}")
+            except Exception as e:
+                logger.exception(f"Error occurred while trying to save agent {agent_d['agent_id']}:\n{e}")
+
     def _get_agent(self, user_id: str, agent_id: str) -> Union[Agent, None]:
         """Get the agent object from the in-memory object store"""
         for d in self.active_agents:
@@ -372,10 +385,11 @@ class SyncServer(Server):
             tool_objs = []
             for name in agent_state.tools:
                 # TODO: This should be a hard failure, but for migration reasons, we patch it for now
-                try:
+                tool_obj = self.tool_manager.get_tool_by_name(tool_name=name, actor=actor)
+                if tool_obj:
                     tool_obj = self.tool_manager.get_tool_by_name(tool_name=name, actor=actor)
                     tool_objs.append(tool_obj)
-                except NoResultFound:
+                else:
                     warnings.warn(f"Tried to retrieve a tool with name {name} from the agent_state, but does not exist in tool db.")
 
             # set agent_state tools to only the names of the available tools
@@ -400,8 +414,10 @@ class SyncServer(Server):
             logger.exception(f"Error occurred while trying to get agent {agent_id}:\n{e}")
             raise
 
-    def _get_or_load_agent(self, agent_id: str) -> Agent:
+    def _get_or_load_agent(self, agent_id: str, caching: bool = True) -> Agent:
         """Check if the agent is in-memory, then load"""
+
+        # Gets the agent state
         agent_state = self.ms.get_agent(agent_id=agent_id)
         if not agent_state:
             raise ValueError(f"Agent does not exist")
@@ -409,11 +425,24 @@ class SyncServer(Server):
         actor = self.user_manager.get_user_by_id(user_id)
 
         logger.debug(f"Checking for agent user_id={user_id} agent_id={agent_id}")
-        # TODO: consider disabling loading cached agents due to potential concurrency issues
-        letta_agent = self._get_agent(user_id=user_id, agent_id=agent_id)
-        if not letta_agent:
-            logger.debug(f"Agent not loaded, loading agent user_id={user_id} agent_id={agent_id}")
+        if caching:
+            # TODO: consider disabling loading cached agents due to potential concurrency issues
+            letta_agent = self._get_agent(user_id=user_id, agent_id=agent_id)
+            if not letta_agent:
+                logger.debug(f"Agent not loaded, loading agent user_id={user_id} agent_id={agent_id}")
+                letta_agent = self._load_agent(agent_id=agent_id, actor=actor)
+        else:
+            # This breaks unit tests in test_local_client.py
             letta_agent = self._load_agent(agent_id=agent_id, actor=actor)
+
+        # letta_agent = self._get_agent(user_id=user_id, agent_id=agent_id)
+        # if not letta_agent:
+        # logger.debug(f"Agent not loaded, loading agent user_id={user_id} agent_id={agent_id}")
+
+        # NOTE: no longer caching, always forcing a lot from the database
+        # Loads the agent objects
+        # letta_agent = self._load_agent(agent_id=agent_id, actor=actor)
+
         return letta_agent
 
     def _step(
@@ -813,10 +842,10 @@ class SyncServer(Server):
             tool_objs = []
             if request.tools:
                 for tool_name in request.tools:
-                    try:
-                        tool_obj = self.tool_manager.get_tool_by_name(tool_name=tool_name, actor=actor)
+                    tool_obj = self.tool_manager.get_tool_by_name(tool_name=tool_name, actor=actor)
+                    if tool_obj:
                         tool_objs.append(tool_obj)
-                    except NoResultFound:
+                    else:
                         warnings.warn(f"Attempted to add a nonexistent tool {tool_name} to agent {request.name}, skipping.")
             # reset the request.tools to only valid tools
             request.tools = [t.name for t in tool_objs]
@@ -1376,8 +1405,9 @@ class SyncServer(Server):
         # Get the agent object (loaded in memory)
         letta_agent = self._get_or_load_agent(agent_id=agent_id)
         assert isinstance(letta_agent.memory, Memory)
-        agent_state = letta_agent.agent_state.model_copy(deep=True)
 
+        letta_agent.update_memory_blocks_from_db()
+        agent_state = letta_agent.agent_state.model_copy(deep=True)
         # Load the tags in for the agent_state
         agent_state.tags = self.agents_tags_manager.get_tags_for_agent(agent_id=agent_id, actor=user)
         return agent_state
@@ -1431,6 +1461,7 @@ class SyncServer(Server):
         # If we modified the memory contents, we need to rebuild the memory block inside the system message
         if modified:
             letta_agent.rebuild_memory()
+            # letta_agent.rebuild_memory(force=True, ms=self.ms)  # This breaks unit tests in test_local_client.py
             # save agent
             save_agent(letta_agent, self.ms)
 
@@ -1723,7 +1754,7 @@ class SyncServer(Server):
     def add_default_external_tools(self, actor: User) -> bool:
         """Add default langchain tools. Return true if successful, false otherwise."""
         success = True
-        tool_creates = ToolCreate.load_default_langchain_tools() + ToolCreate.load_default_crewai_tools()
+        tool_creates = ToolCreate.load_default_langchain_tools()
         if tool_settings.composio_api_key:
             tool_creates += ToolCreate.load_default_composio_tools()
         for tool_create in tool_creates:
@@ -1817,3 +1848,119 @@ class SyncServer(Server):
         # Get the current message
         letta_agent = self._get_or_load_agent(agent_id=agent_id)
         return letta_agent.get_context_window()
+
+    def update_agent_memory_label(self, user_id: str, agent_id: str, current_block_label: str, new_block_label: str) -> Memory:
+        """Update the label of a block in an agent's memory"""
+
+        # Get the user
+        user = self.user_manager.get_user_by_id(user_id=user_id)
+
+        # Link a block to an agent's memory
+        letta_agent = self._get_or_load_agent(agent_id=agent_id)
+        letta_agent.memory.update_block_label(current_label=current_block_label, new_label=new_block_label)
+        assert new_block_label in letta_agent.memory.list_block_labels()
+        self.block_manager.create_or_update_block(block=letta_agent.memory.get_block(new_block_label), actor=user)
+
+        # check that the block was updated
+        updated_block = self.block_manager.get_block_by_id(block_id=letta_agent.memory.get_block(new_block_label).id, actor=user)
+
+        # Recompile the agent memory
+        letta_agent.rebuild_memory(force=True, ms=self.ms)
+
+        # save agent
+        save_agent(letta_agent, self.ms)
+
+        updated_agent = self.ms.get_agent(agent_id=agent_id)
+        if updated_agent is None:
+            raise ValueError(f"Agent with id {agent_id} not found after linking block")
+        assert new_block_label in updated_agent.memory.list_block_labels()
+        assert current_block_label not in updated_agent.memory.list_block_labels()
+        return updated_agent.memory
+
+    def link_block_to_agent_memory(self, user_id: str, agent_id: str, block_id: str) -> Memory:
+        """Link a block to an agent's memory"""
+
+        # Get the user
+        user = self.user_manager.get_user_by_id(user_id=user_id)
+
+        # Get the block first
+        block = self.block_manager.get_block_by_id(block_id=block_id, actor=user)
+        if block is None:
+            raise ValueError(f"Block with id {block_id} not found")
+
+        # Link a block to an agent's memory
+        letta_agent = self._get_or_load_agent(agent_id=agent_id)
+        letta_agent.memory.link_block(block=block)
+        assert block.label in letta_agent.memory.list_block_labels()
+
+        # Recompile the agent memory
+        letta_agent.rebuild_memory(force=True, ms=self.ms)
+
+        # save agent
+        save_agent(letta_agent, self.ms)
+
+        updated_agent = self.ms.get_agent(agent_id=agent_id)
+        if updated_agent is None:
+            raise ValueError(f"Agent with id {agent_id} not found after linking block")
+        assert block.label in updated_agent.memory.list_block_labels()
+
+        return updated_agent.memory
+
+    def unlink_block_from_agent_memory(self, user_id: str, agent_id: str, block_label: str, delete_if_no_ref: bool = True) -> Memory:
+        """Unlink a block from an agent's memory. If the block is not linked to any agent, delete it."""
+
+        # Get the user
+        user = self.user_manager.get_user_by_id(user_id=user_id)
+
+        # Link a block to an agent's memory
+        letta_agent = self._get_or_load_agent(agent_id=agent_id)
+        unlinked_block = letta_agent.memory.unlink_block(block_label=block_label)
+        assert unlinked_block.label not in letta_agent.memory.list_block_labels()
+
+        # Check if the block is linked to any other agent
+        # TODO needs reference counting GC to handle loose blocks
+        # block = self.block_manager.get_block_by_id(block_id=unlinked_block.id, actor=user)
+        # if block is None:
+        # raise ValueError(f"Block with id {block_id} not found")
+
+        # Recompile the agent memory
+        letta_agent.rebuild_memory(force=True, ms=self.ms)
+
+        # save agent
+        save_agent(letta_agent, self.ms)
+
+        updated_agent = self.ms.get_agent(agent_id=agent_id)
+        if updated_agent is None:
+            raise ValueError(f"Agent with id {agent_id} not found after linking block")
+        assert unlinked_block.label not in updated_agent.memory.list_block_labels()
+        return updated_agent.memory
+
+    def update_agent_memory_limit(self, user_id: str, agent_id: str, block_label: str, limit: int) -> Memory:
+        """Update the limit of a block in an agent's memory"""
+
+        # Get the user
+        user = self.user_manager.get_user_by_id(user_id=user_id)
+
+        # Link a block to an agent's memory
+        letta_agent = self._get_or_load_agent(agent_id=agent_id)
+        letta_agent.memory.update_block_limit(label=block_label, limit=limit)
+        assert block_label in letta_agent.memory.list_block_labels()
+
+        # write out the update the database
+        self.block_manager.create_or_update_block(block=letta_agent.memory.get_block(block_label), actor=user)
+
+        # check that the block was updated
+        updated_block = self.block_manager.get_block_by_id(block_id=letta_agent.memory.get_block(block_label).id, actor=user)
+        assert updated_block and updated_block.limit == limit
+
+        # Recompile the agent memory
+        letta_agent.rebuild_memory(force=True, ms=self.ms)
+
+        # save agent
+        save_agent(letta_agent, self.ms)
+
+        updated_agent = self.ms.get_agent(agent_id=agent_id)
+        if updated_agent is None:
+            raise ValueError(f"Agent with id {agent_id} not found after linking block")
+        assert updated_agent.memory.get_block(label=block_label).limit == limit
+        return updated_agent.memory

letta/services/block_manager.py

@@ -28,8 +28,10 @@ class BlockManager:
             self.update_block(block.id, update_data, actor)
         else:
             with self.session_maker() as session:
+                # Always write the organization_id
+                block.organization_id = actor.organization_id
                 data = block.model_dump(exclude_none=True)
-                block = BlockModel(**data, organization_id=actor.organization_id)
+                block = BlockModel(**data)
                 block.create(session, actor=actor)
             return block.to_pydantic()
 

letta/services/blocks_agents_manager.py

@@ -0,0 +1,84 @@
+import warnings
+from typing import List
+
+from letta.orm.blocks_agents import BlocksAgents as BlocksAgentsModel
+from letta.orm.errors import NoResultFound
+from letta.schemas.blocks_agents import BlocksAgents as PydanticBlocksAgents
+from letta.utils import enforce_types
+
+
+# TODO: DELETE THIS ASAP
+# TODO: So we have a patch where we manually specify CRUD operations
+# TODO: This is because Agent is NOT migrated to the ORM yet
+# TODO: Once we migrate Agent to the ORM, we should deprecate any agents relationship table managers
+class BlocksAgentsManager:
+    """Manager class to handle business logic related to Blocks and Agents."""
+
+    def __init__(self):
+        from letta.server.server import db_context
+
+        self.session_maker = db_context
+
+    @enforce_types
+    def add_block_to_agent(self, agent_id: str, block_id: str, block_label: str) -> PydanticBlocksAgents:
+        """Add a block to an agent. If the label already exists on that agent, this will error."""
+        with self.session_maker() as session:
+            try:
+                # Check if the block-label combination already exists for this agent
+                blocks_agents_record = BlocksAgentsModel.read(db_session=session, agent_id=agent_id, block_label=block_label)
+                warnings.warn(f"Block label '{block_label}' already exists for agent '{agent_id}'.")
+            except NoResultFound:
+                blocks_agents_record = PydanticBlocksAgents(agent_id=agent_id, block_id=block_id, block_label=block_label)
+                blocks_agents_record = BlocksAgentsModel(**blocks_agents_record.model_dump(exclude_none=True))
+                blocks_agents_record.create(session)
+
+            return blocks_agents_record.to_pydantic()
+
+    @enforce_types
+    def remove_block_with_label_from_agent(self, agent_id: str, block_label: str) -> PydanticBlocksAgents:
+        """Remove a block with a label from an agent."""
+        with self.session_maker() as session:
+            try:
+                # Find and delete the block-label association for the agent
+                blocks_agents_record = BlocksAgentsModel.read(db_session=session, agent_id=agent_id, block_label=block_label)
+                blocks_agents_record.hard_delete(session)
+                return blocks_agents_record.to_pydantic()
+            except NoResultFound:
+                raise ValueError(f"Block label '{block_label}' not found for agent '{agent_id}'.")
+
+    @enforce_types
+    def remove_block_with_id_from_agent(self, agent_id: str, block_id: str) -> PydanticBlocksAgents:
+        """Remove a block with a label from an agent."""
+        with self.session_maker() as session:
+            try:
+                # Find and delete the block-label association for the agent
+                blocks_agents_record = BlocksAgentsModel.read(db_session=session, agent_id=agent_id, block_id=block_id)
+                blocks_agents_record.hard_delete(session)
+                return blocks_agents_record.to_pydantic()
+            except NoResultFound:
+                raise ValueError(f"Block id '{block_id}' not found for agent '{agent_id}'.")
+
+    @enforce_types
+    def update_block_id_for_agent(self, agent_id: str, block_label: str, new_block_id: str) -> PydanticBlocksAgents:
+        """Update the block ID for a specific block label for an agent."""
+        with self.session_maker() as session:
+            try:
+                blocks_agents_record = BlocksAgentsModel.read(db_session=session, agent_id=agent_id, block_label=block_label)
+                blocks_agents_record.block_id = new_block_id
+                return blocks_agents_record.to_pydantic()
+            except NoResultFound:
+                raise ValueError(f"Block label '{block_label}' not found for agent '{agent_id}'.")
+
+    @enforce_types
+    def list_block_ids_for_agent(self, agent_id: str) -> List[str]:
+        """List all blocks associated with a specific agent."""
+        with self.session_maker() as session:
+            blocks_agents_record = BlocksAgentsModel.list(db_session=session, agent_id=agent_id)
+            return [record.block_id for record in blocks_agents_record]
+
+    @enforce_types
+    def list_agent_ids_with_block(self, block_id: str) -> List[str]:
+        """List all agents associated with a specific block."""
+        with self.session_maker() as session:
+            blocks_agents_record = BlocksAgentsModel.list(db_session=session, block_id=block_id)
+            return [record.agent_id for record in blocks_agents_record]

letta/services/sandbox_config_manager.py

@@ -0,0 +1,256 @@
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from letta.log import get_logger
+from letta.orm.errors import NoResultFound
+from letta.orm.sandbox_config import SandboxConfig as SandboxConfigModel
+from letta.orm.sandbox_config import SandboxEnvironmentVariable as SandboxEnvVarModel
+from letta.schemas.sandbox_config import E2BSandboxConfig, LocalSandboxConfig
+from letta.schemas.sandbox_config import SandboxConfig as PydanticSandboxConfig
+from letta.schemas.sandbox_config import SandboxConfigCreate, SandboxConfigUpdate
+from letta.schemas.sandbox_config import SandboxEnvironmentVariable as PydanticEnvVar
+from letta.schemas.sandbox_config import (
+    SandboxEnvironmentVariableCreate,
+    SandboxEnvironmentVariableUpdate,
+    SandboxType,
+)
+from letta.schemas.user import User as PydanticUser
+from letta.utils import enforce_types, printd
+
+logger = get_logger(__name__)
+
+
+class SandboxConfigManager:
+    """Manager class to handle business logic related to SandboxConfig and SandboxEnvironmentVariable."""
+
+    def __init__(self, settings):
+        from letta.server.server import db_context
+
+        self.session_maker = db_context
+        self.e2b_template_id = settings.e2b_sandbox_template_id
+
+    @enforce_types
+    def get_or_create_default_sandbox_config(self, sandbox_type: SandboxType, actor: PydanticUser) -> PydanticSandboxConfig:
+        sandbox_config = self.get_sandbox_config_by_type(sandbox_type, actor=actor)
+        if not sandbox_config:
+            logger.info(f"Creating new sandbox config of type {sandbox_type}, none found for organization {actor.organization_id}.")
+
+            # TODO: Add more sandbox types later
+            if sandbox_type == SandboxType.E2B:
+                default_config = E2BSandboxConfig(template=self.e2b_template_id).model_dump(exclude_none=True)
+            else:
+                default_local_sandbox_path = str(Path(__file__).parent / "tool_sandbox_env")
+                default_config = LocalSandboxConfig(sandbox_dir=default_local_sandbox_path).model_dump(exclude_none=True)
+
+            sandbox_config = self.create_or_update_sandbox_config(SandboxConfigCreate(config=default_config), actor=actor)
+        return sandbox_config
+
+    @enforce_types
+    def create_or_update_sandbox_config(self, sandbox_config_create: SandboxConfigCreate, actor: PydanticUser) -> PydanticSandboxConfig:
+        """Create or update a sandbox configuration based on the PydanticSandboxConfig schema."""
+        config = sandbox_config_create.config
+        sandbox_type = config.type
+        sandbox_config = PydanticSandboxConfig(
+            type=sandbox_type, config=config.model_dump(exclude_none=True), organization_id=actor.organization_id
+        )
+
+        # Attempt to retrieve the existing sandbox configuration by type within the organization
+        db_sandbox = self.get_sandbox_config_by_type(sandbox_config.type, actor=actor)
+        if db_sandbox:
+            # Prepare the update data, excluding fields that should not be reset
+            update_data = sandbox_config.model_dump(exclude_unset=True, exclude_none=True)
+            update_data = {key: value for key, value in update_data.items() if getattr(db_sandbox, key) != value}
+
+            # If there are changes, update the sandbox configuration
+            if update_data:
+                db_sandbox = self.update_sandbox_config(db_sandbox.id, SandboxConfigUpdate(**update_data), actor)
+            else:
+                printd(
+                    f"`create_or_update_sandbox_config` was called with user_id={actor.id}, organization_id={actor.organization_id}, "
+                    f"type={sandbox_config.type}, but found existing configuration with nothing to update."
+                )
+
+            return db_sandbox
+        else:
+            # If the sandbox configuration doesn't exist, create a new one
+            with self.session_maker() as session:
+                db_sandbox = SandboxConfigModel(**sandbox_config.model_dump(exclude_none=True))
+                db_sandbox.create(session, actor=actor)
+                return db_sandbox.to_pydantic()
+
+    @enforce_types
+    def update_sandbox_config(
+        self, sandbox_config_id: str, sandbox_update: SandboxConfigUpdate, actor: PydanticUser
+    ) -> PydanticSandboxConfig:
+        """Update an existing sandbox configuration."""
+        with self.session_maker() as session:
+            sandbox = SandboxConfigModel.read(db_session=session, identifier=sandbox_config_id, actor=actor)
+            # We need to check that the sandbox_update provided is the same type as the original sandbox
+            if sandbox.type != sandbox_update.config.type:
+                raise ValueError(
+                    f"Mismatched type for sandbox config update: tried to update sandbox_config of type {sandbox.type} with config of type {sandbox_update.config.type}"
+                )
+
+            update_data = sandbox_update.model_dump(exclude_unset=True, exclude_none=True)
+            update_data = {key: value for key, value in update_data.items() if getattr(sandbox, key) != value}
+
+            if update_data:
+                for key, value in update_data.items():
+                    setattr(sandbox, key, value)
+                sandbox.update(db_session=session, actor=actor)
+            else:
+                printd(
+                    f"`update_sandbox_config` called with user_id={actor.id}, organization_id={actor.organization_id}, "
+                    f"name={sandbox.type}, but nothing to update."
+                )
+            return sandbox.to_pydantic()
+
+    @enforce_types
+    def delete_sandbox_config(self, sandbox_config_id: str, actor: PydanticUser) -> PydanticSandboxConfig:
+        """Delete a sandbox configuration by its ID."""
+        with self.session_maker() as session:
+            sandbox = SandboxConfigModel.read(db_session=session, identifier=sandbox_config_id, actor=actor)
+            sandbox.hard_delete(db_session=session, actor=actor)
+            return sandbox.to_pydantic()
+
+    @enforce_types
+    def list_sandbox_configs(
+        self, actor: PydanticUser, cursor: Optional[str] = None, limit: Optional[int] = 50
+    ) -> List[PydanticSandboxConfig]:
+        """List all sandbox configurations with optional pagination."""
+        with self.session_maker() as session:
+            sandboxes = SandboxConfigModel.list(
+                db_session=session,
+                cursor=cursor,
+                limit=limit,
+                organization_id=actor.organization_id,
+            )
+            return [sandbox.to_pydantic() for sandbox in sandboxes]
+
+    @enforce_types
+    def get_sandbox_config_by_id(self, sandbox_config_id: str, actor: Optional[PydanticUser] = None) -> Optional[PydanticSandboxConfig]:
+        """Retrieve a sandbox configuration by its ID."""
+        with self.session_maker() as session:
+            try:
+                sandbox = SandboxConfigModel.read(db_session=session, identifier=sandbox_config_id, actor=actor)
+                return sandbox.to_pydantic()
+            except NoResultFound:
+                return None
+
+    @enforce_types
+    def get_sandbox_config_by_type(self, type: SandboxType, actor: Optional[PydanticUser] = None) -> Optional[PydanticSandboxConfig]:
+        """Retrieve a sandbox config by its type."""
+        with self.session_maker() as session:
+            try:
+                sandboxes = SandboxConfigModel.list(
+                    db_session=session,
+                    type=type,
+                    organization_id=actor.organization_id,
+                    limit=1,
+                )
+                if sandboxes:
+                    return sandboxes[0].to_pydantic()
+                return None
+            except NoResultFound:
+                return None
+
+    @enforce_types
+    def create_sandbox_env_var(
+        self, env_var_create: SandboxEnvironmentVariableCreate, sandbox_config_id: str, actor: PydanticUser
+    ) -> PydanticEnvVar:
+        """Create a new sandbox environment variable."""
+        env_var = PydanticEnvVar(**env_var_create.model_dump(), sandbox_config_id=sandbox_config_id, organization_id=actor.organization_id)
+
+        db_env_var = self.get_sandbox_env_var_by_key_and_sandbox_config_id(env_var.key, env_var.sandbox_config_id, actor=actor)
+        if db_env_var:
+            update_data = env_var.model_dump(exclude_unset=True, exclude_none=True)
+            update_data = {key: value for key, value in update_data.items() if getattr(db_env_var, key) != value}
+            # If there are changes, update the environment variable
+            if update_data:
+                db_env_var = self.update_sandbox_env_var(db_env_var.id, SandboxEnvironmentVariableUpdate(**update_data), actor)
+            else:
+                printd(
+                    f"`create_or_update_sandbox_env_var` was called with user_id={actor.id}, organization_id={actor.organization_id}, "
+                    f"key={env_var.key}, but found existing variable with nothing to update."
+                )
+
+            return db_env_var
+        else:
+            with self.session_maker() as session:
+                env_var = SandboxEnvVarModel(**env_var.model_dump(exclude_none=True))
+                env_var.create(session, actor=actor)
+            return env_var.to_pydantic()
+
+    @enforce_types
+    def update_sandbox_env_var(
+        self, env_var_id: str, env_var_update: SandboxEnvironmentVariableUpdate, actor: PydanticUser
+    ) -> PydanticEnvVar:
+        """Update an existing sandbox environment variable."""
+        with self.session_maker() as session:
+            env_var = SandboxEnvVarModel.read(db_session=session, identifier=env_var_id, actor=actor)
+            update_data = env_var_update.model_dump(exclude_unset=True, exclude_none=True)
+            update_data = {key: value for key, value in update_data.items() if getattr(env_var, key) != value}
+
+            if update_data:
+                for key, value in update_data.items():
+                    setattr(env_var, key, value)
+                env_var.update(db_session=session, actor=actor)
+            else:
+                printd(
+                    f"`update_sandbox_env_var` called with user_id={actor.id}, organization_id={actor.organization_id}, "
+                    f"key={env_var.key}, but nothing to update."
+                )
+            return env_var.to_pydantic()
+
+    @enforce_types
+    def delete_sandbox_env_var(self, env_var_id: str, actor: PydanticUser) -> PydanticEnvVar:
+        """Delete a sandbox environment variable by its ID."""
+        with self.session_maker() as session:
+            env_var = SandboxEnvVarModel.read(db_session=session, identifier=env_var_id, actor=actor)
+            env_var.hard_delete(db_session=session, actor=actor)
+            return env_var.to_pydantic()
+
+    @enforce_types
+    def list_sandbox_env_vars(
+        self, sandbox_config_id: str, actor: PydanticUser, cursor: Optional[str] = None, limit: Optional[int] = 50
+    ) -> List[PydanticEnvVar]:
+        """List all sandbox environment variables with optional pagination."""
+        with self.session_maker() as session:
+            env_vars = SandboxEnvVarModel.list(
+                db_session=session,
+                cursor=cursor,
+                limit=limit,
+                organization_id=actor.organization_id,
+                sandbox_config_id=sandbox_config_id,
+            )
+            return [env_var.to_pydantic() for env_var in env_vars]
+
+    @enforce_types
+    def get_sandbox_env_vars_as_dict(
+        self, sandbox_config_id: str, actor: PydanticUser, cursor: Optional[str] = None, limit: Optional[int] = 50
+    ) -> Dict[str, str]:
+        env_vars = self.list_sandbox_env_vars(sandbox_config_id, actor, cursor, limit)
+        result = {}
+        for env_var in env_vars:
+            result[env_var.key] = env_var.value
+        return result
+
+    @enforce_types
+    def get_sandbox_env_var_by_key_and_sandbox_config_id(
+        self, key: str, sandbox_config_id: str, actor: Optional[PydanticUser] = None
+    ) -> Optional[PydanticEnvVar]:
+        """Retrieve a sandbox environment variable by its key and sandbox_config_id."""
+        with self.session_maker() as session:
+            try:
+                env_var = SandboxEnvVarModel.list(
+                    db_session=session,
+                    key=key,
+                    sandbox_config_id=sandbox_config_id,
+                    organization_id=actor.organization_id,
+                    limit=1,
+                )
+                if env_var:
+                    return env_var[0].to_pydantic()
+                return None
+            except NoResultFound:
+                return None