letta-nightly 0.11.7.dev20251007104119__py3-none-any.whl → 0.12.0.dev20251009104148__py3-none-any.whl

letta/server/rest_api/routers/v1/runs.py

@@ -7,12 +7,13 @@ from pydantic import Field
 from letta.data_sources.redis_client import NoopAsyncRedisClient, get_redis_client
 from letta.helpers.datetime_helpers import get_utc_time
 from letta.orm.errors import NoResultFound
-from letta.schemas.enums import JobStatus, JobType
+from letta.schemas.enums import RunStatus
 from letta.schemas.letta_message import LettaMessageUnion
 from letta.schemas.letta_request import RetrieveStreamRequest
 from letta.schemas.letta_stop_reason import StopReasonType
 from letta.schemas.openai.chat_completion_response import UsageStatistics
 from letta.schemas.run import Run
+from letta.schemas.run_metrics import RunMetrics
 from letta.schemas.step import Step
 from letta.server.rest_api.dependencies import HeaderParams, get_headers, get_letta_server
 from letta.server.rest_api.redis_stream_manager import redis_sse_stream_generator
@@ -22,81 +23,124 @@ from letta.server.rest_api.streaming_response import (
     cancellation_aware_stream_wrapper,
 )
 from letta.server.server import SyncServer
+from letta.services.lettuce import LettuceClient
+from letta.services.run_manager import RunManager
 from letta.settings import settings
 
 router = APIRouter(prefix="/runs", tags=["runs"])
 
 
+def convert_statuses_to_enum(statuses: Optional[List[str]]) -> Optional[List[RunStatus]]:
+    """Convert a list of status strings to RunStatus enum values.
+
+    Args:
+        statuses: List of status strings or None
+
+    Returns:
+        List of RunStatus enum values or None if input is None
+    """
+    if statuses is None:
+        return None
+    return [RunStatus(status) for status in statuses]
+
+
 @router.get("/", response_model=List[Run], operation_id="list_runs")
-def list_runs(
+async def list_runs(
     server: "SyncServer" = Depends(get_letta_server),
-    agent_ids: Optional[List[str]] = Query(None, description="The unique identifier of the agent associated with the run."),
+    agent_id: Optional[str] = Query(None, description="The unique identifier of the agent associated with the run."),
+    agent_ids: Optional[List[str]] = Query(
+        None,
+        description="The unique identifiers of the agents associated with the run. Deprecated in favor of agent_id field.",
+        deprecated=True,
+    ),
+    statuses: Optional[List[str]] = Query(None, description="Filter runs by status. Can specify multiple statuses."),
     background: Optional[bool] = Query(None, description="If True, filters for runs that were created in background mode."),
     stop_reason: Optional[StopReasonType] = Query(None, description="Filter runs by stop reason."),
-    after: Optional[str] = Query(None, description="Cursor for pagination"),
-    before: Optional[str] = Query(None, description="Cursor for pagination"),
-    limit: Optional[int] = Query(50, description="Maximum number of runs to return"),
+    before: Optional[str] = Query(
+        None, description="Run ID cursor for pagination. Returns runs that come before this run ID in the specified sort order"
+    ),
+    after: Optional[str] = Query(
+        None, description="Run ID cursor for pagination. Returns runs that come after this run ID in the specified sort order"
+    ),
+    limit: Optional[int] = Query(100, description="Maximum number of runs to return"),
+    order: Literal["asc", "desc"] = Query(
+        "desc", description="Sort order for runs by creation time. 'asc' for oldest first, 'desc' for newest first"
+    ),
+    order_by: Literal["created_at"] = Query("created_at", description="Field to sort by"),
     active: bool = Query(False, description="Filter for active runs."),
     ascending: bool = Query(
         False,
-        description="Whether to sort agents oldest to newest (True) or newest to oldest (False, default)",
+        description="Whether to sort agents oldest to newest (True) or newest to oldest (False, default). Deprecated in favor of order field.",
+        deprecated=True,
     ),
     headers: HeaderParams = Depends(get_headers),
 ):
     """
     List all runs.
     """
-    actor = server.user_manager.get_user_or_default(user_id=headers.actor_id)
-    statuses = None
-    if active:
-        statuses = [JobStatus.created, JobStatus.running]
-
-    runs = [
-        Run.from_job(job)
-        for job in server.job_manager.list_jobs(
-            actor=actor,
-            statuses=statuses,
-            job_type=JobType.RUN,
-            limit=limit,
-            before=before,
-            after=after,
-            ascending=False,
-            stop_reason=stop_reason,
-        )
-    ]
-    if agent_ids:
-        runs = [run for run in runs if "agent_id" in run.metadata and run.metadata["agent_id"] in agent_ids]
-    if background is not None:
-        runs = [run for run in runs if "background" in run.metadata and run.metadata["background"] == background]
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
+    runs_manager = RunManager()
+
+    # Handle backwards compatibility: if statuses not provided but active=True, filter by active statuses
+    if statuses is None and active:
+        statuses = [RunStatus.created, RunStatus.running]
+
+    if agent_id:
+        # NOTE: we are deprecating agent_ids so this will the primary path soon
+        agent_ids = [agent_id]
+
+    # Handle backward compatibility: if ascending is explicitly set, use it; otherwise use order
+    if ascending is not False:
+        # ascending was explicitly set to True
+        sort_ascending = ascending
+    else:
+        # Use the new order parameter
+        sort_ascending = order == "asc"
+
+    # Convert string statuses to RunStatus enum
+    parsed_statuses = convert_statuses_to_enum(statuses)
+
+    runs = await runs_manager.list_runs(
+        actor=actor,
+        agent_ids=agent_ids,
+        statuses=parsed_statuses,
+        limit=limit,
+        before=before,
+        after=after,
+        ascending=sort_ascending,
+        stop_reason=stop_reason,
+        background=background,
+    )
     return runs
 
 
 @router.get("/active", response_model=List[Run], operation_id="list_active_runs", deprecated=True)
-def list_active_runs(
+async def list_active_runs(
     server: "SyncServer" = Depends(get_letta_server),
-    agent_ids: Optional[List[str]] = Query(None, description="The unique identifier of the agent associated with the run."),
+    agent_id: Optional[str] = Query(None, description="The unique identifier of the agent associated with the run."),
     background: Optional[bool] = Query(None, description="If True, filters for runs that were created in background mode."),
     headers: HeaderParams = Depends(get_headers),
 ):
     """
     List all active runs.
     """
-    actor = server.user_manager.get_user_or_default(user_id=headers.actor_id)
-
-    active_runs = server.job_manager.list_jobs(actor=actor, statuses=[JobStatus.created, JobStatus.running], job_type=JobType.RUN)
-    active_runs = [Run.from_job(job) for job in active_runs]
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
+    runs_manager = RunManager()
 
-    if agent_ids:
-        active_runs = [run for run in active_runs if "agent_id" in run.metadata and run.metadata["agent_id"] in agent_ids]
+    if agent_id:
+        agent_ids = [agent_id]
+    else:
+        agent_ids = None
 
-    if background is not None:
-        active_runs = [run for run in active_runs if "background" in run.metadata and run.metadata["background"] == background]
+    active_runs = await runs_manager.list_runs(
+        actor=actor, statuses=[RunStatus.created, RunStatus.running], agent_ids=agent_ids, background=background
+    )
 
     return active_runs
 
 
 @router.get("/{run_id}", response_model=Run, operation_id="retrieve_run")
-def retrieve_run(
+async def retrieve_run(
     run_id: str,
     headers: HeaderParams = Depends(get_headers),
     server: "SyncServer" = Depends(get_letta_server),
@@ -104,11 +148,29 @@ def retrieve_run(
     """
     Get the status of a run.
     """
-    actor = server.user_manager.get_user_or_default(user_id=headers.actor_id)
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
+    runs_manager = RunManager()
 
     try:
-        job = server.job_manager.get_job_by_id(job_id=run_id, actor=actor)
-        return Run.from_job(job)
+        run = await runs_manager.get_run_by_id(run_id=run_id, actor=actor)
+
+        use_lettuce = run.metadata and run.metadata.get("lettuce")
+        if use_lettuce and run.status not in [RunStatus.completed, RunStatus.failed, RunStatus.cancelled]:
+            lettuce_client = await LettuceClient.create()
+            status = await lettuce_client.get_status()
+
+            # Map the status to our enum
+            run_status = run.status
+            if status == "RUNNING":
+                run_status = RunStatus.running
+            elif status == "COMPLETED":
+                run_status = RunStatus.completed
+            elif status == "FAILED":
+                run_status = RunStatus.failed
+            elif status == "CANCELLED":
+                run_status = RunStatus.cancelled
+            run.status = run_status
+        return run
     except NoResultFound:
         raise HTTPException(status_code=404, detail="Run not found")
 
@@ -137,26 +199,15 @@ async def list_run_messages(
     order: Literal["asc", "desc"] = Query(
         "asc", description="Sort order for messages by creation time. 'asc' for oldest first, 'desc' for newest first"
     ),
+    order_by: Literal["created_at"] = Query("created_at", description="Field to sort by"),
 ):
     """Get response messages associated with a run."""
     actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
-
-    try:
-        messages = server.job_manager.get_run_messages(
-            run_id=run_id,
-            actor=actor,
-            limit=limit,
-            before=before,
-            after=after,
-            ascending=(order == "asc"),
-        )
-        return messages
-    except NoResultFound as e:
-        raise HTTPException(status_code=404, detail=str(e))
+    return await server.run_manager.get_run_messages(run_id=run_id, actor=actor, before=before, after=after, limit=limit, order=order)
 
 
 @router.get("/{run_id}/usage", response_model=UsageStatistics, operation_id="retrieve_run_usage")
-def retrieve_run_usage(
+async def retrieve_run_usage(
     run_id: str,
     headers: HeaderParams = Depends(get_headers),
     server: "SyncServer" = Depends(get_letta_server),
@@ -164,15 +215,33 @@ def retrieve_run_usage(
     """
     Get usage statistics for a run.
     """
-    actor = server.user_manager.get_user_or_default(user_id=headers.actor_id)
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
+    runs_manager = RunManager()
 
     try:
-        usage = server.job_manager.get_job_usage(job_id=run_id, actor=actor)
+        usage = await runs_manager.get_run_usage(run_id=run_id, actor=actor)
         return usage
     except NoResultFound:
         raise HTTPException(status_code=404, detail=f"Run '{run_id}' not found")
 
 
+@router.get("/{run_id}/metrics", response_model=RunMetrics, operation_id="retrieve_metrics_for_run")
+async def retrieve_metrics_for_run(
+    run_id: str,
+    headers: HeaderParams = Depends(get_headers),
+    server: "SyncServer" = Depends(get_letta_server),
+):
+    """
+    Get run metrics by run ID.
+    """
+    try:
+        actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
+        runs_manager = RunManager()
+        return await runs_manager.get_run_metrics_async(run_id=run_id, actor=actor)
+    except NoResultFound:
+        raise HTTPException(status_code=404, detail="Run metrics not found")
+
+
 @router.get(
     "/{run_id}/steps",
     response_model=List[Step],
@@ -185,40 +254,25 @@ async def list_run_steps(
     before: Optional[str] = Query(None, description="Cursor for pagination"),
     after: Optional[str] = Query(None, description="Cursor for pagination"),
     limit: Optional[int] = Query(100, description="Maximum number of messages to return"),
-    order: str = Query(
-        "desc", description="Sort order by the created_at timestamp of the objects. asc for ascending order and desc for descending order."
+    order: Literal["asc", "desc"] = Query(
+        "desc", description="Sort order for steps by creation time. 'asc' for oldest first, 'desc' for newest first"
     ),
+    order_by: Literal["created_at"] = Query("created_at", description="Field to sort by"),
 ):
     """
-    Get messages associated with a run with filtering options.
-
-    Args:
-        run_id: ID of the run
-        before: A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list.
-        after: A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.
-        limit: Maximum number of steps to return
-        order: Sort order by the created_at timestamp of the objects. asc for ascending order and desc for descending order.
-
-    Returns:
-        A list of steps associated with the run.
+    Get steps associated with a run with filtering options.
     """
-    if order not in ["asc", "desc"]:
-        raise HTTPException(status_code=400, detail="Order must be 'asc' or 'desc'")
-
     actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
+    runs_manager = RunManager()
 
-    try:
-        steps = server.job_manager.get_job_steps(
-            job_id=run_id,
-            actor=actor,
-            limit=limit,
-            before=before,
-            after=after,
-            ascending=(order == "asc"),
-        )
-        return steps
-    except NoResultFound as e:
-        raise HTTPException(status_code=404, detail=str(e))
+    return await runs_manager.get_run_steps(
+        run_id=run_id,
+        actor=actor,
+        limit=limit,
+        before=before,
+        after=after,
+        ascending=(order == "asc"),
+    )
 
 
 @router.delete("/{run_id}", response_model=Run, operation_id="delete_run")
@@ -231,12 +285,8 @@ async def delete_run(
     Delete a run by its run_id.
     """
     actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
-
-    try:
-        job = await server.job_manager.delete_job_by_id_async(job_id=run_id, actor=actor)
-        return Run.from_job(job)
-    except NoResultFound:
-        raise HTTPException(status_code=404, detail="Run not found")
+    runs_manager = RunManager()
+    return await runs_manager.delete_run_by_id(run_id=run_id, actor=actor)
 
 
 @router.post(
@@ -278,14 +328,14 @@ async def retrieve_stream(
     server: "SyncServer" = Depends(get_letta_server),
 ):
     actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
+    runs_manager = RunManager()
+
     try:
-        job = server.job_manager.get_job_by_id(job_id=run_id, actor=actor)
+        run = await runs_manager.get_run_by_id(run_id=run_id, actor=actor)
     except NoResultFound:
         raise HTTPException(status_code=404, detail="Run not found")
 
-    run = Run.from_job(job)
-
-    if "background" not in run.metadata or not run.metadata["background"]:
+    if not run.background:
         raise HTTPException(status_code=400, detail="Run was not created in background mode, so it cannot be retrieved.")
 
     if run.created_at < get_utc_time() - timedelta(hours=3):
@@ -314,8 +364,8 @@ async def retrieve_stream(
     if settings.enable_cancellation_aware_streaming:
         stream = cancellation_aware_stream_wrapper(
             stream_generator=stream,
-            job_manager=server.job_manager,
-            job_id=run_id,
+            run_manager=server.run_manager,
+            run_id=run_id,
             actor=actor,
         )
 

letta/server/rest_api/routers/v1/sandbox_configs.py

@@ -2,8 +2,9 @@ import os
 import shutil
 from typing import List, Optional
 
-from fastapi import APIRouter, Depends, HTTPException, Query
+from fastapi import APIRouter, Depends, Query
 
+from letta.errors import LettaInvalidArgumentError
 from letta.log import get_logger
 from letta.schemas.enums import SandboxType
 from letta.schemas.environment_variables import (
@@ -68,9 +69,8 @@ async def create_custom_local_sandbox_config(
     """
     # Ensure the incoming config is of type LOCAL
     if local_sandbox_config.type != SandboxType.LOCAL:
-        raise HTTPException(
-            status_code=400,
-            detail=f"Provided config must be of type '{SandboxType.LOCAL.value}'.",
+        raise LettaInvalidArgumentError(
+            f"Provided config must be of type '{SandboxType.LOCAL.value}'.", argument_name="local_sandbox_config.type"
         )
 
     # Retrieve the user (actor)
@@ -138,25 +138,16 @@ async def force_recreate_local_sandbox_venv(
 
     # Check if venv exists, and delete if necessary
     if os.path.isdir(venv_path):
-        try:
-            shutil.rmtree(venv_path)
-            logger.info(f"Deleted existing virtual environment at: {venv_path}")
-        except Exception as e:
-            raise HTTPException(status_code=500, detail=f"Failed to delete existing venv: {e}")
+        shutil.rmtree(venv_path)
+        logger.info(f"Deleted existing virtual environment at: {venv_path}")
 
     # Recreate the virtual environment
-    try:
-        create_venv_for_local_sandbox(sandbox_dir_path=sandbox_dir, venv_path=str(venv_path), env=os.environ.copy(), force_recreate=True)
-        logger.info(f"Successfully recreated virtual environment at: {venv_path}")
-    except Exception as e:
-        raise HTTPException(status_code=500, detail=f"Failed to recreate venv: {e}")
+    create_venv_for_local_sandbox(sandbox_dir_path=sandbox_dir, venv_path=str(venv_path), env=os.environ.copy(), force_recreate=True)
+    logger.info(f"Successfully recreated virtual environment at: {venv_path}")
 
     # Install pip requirements
-    try:
-        install_pip_requirements_for_sandbox(local_configs=local_configs, env=os.environ.copy())
-        logger.info(f"Successfully installed pip requirements for venv at: {venv_path}")
-    except Exception as e:
-        raise HTTPException(status_code=500, detail=f"Failed to install pip requirements: {e}")
+    install_pip_requirements_for_sandbox(local_configs=local_configs, env=os.environ.copy())
+    logger.info(f"Successfully installed pip requirements for venv at: {venv_path}")
 
     return sbx_config