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

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

@@ -1,11 +1,11 @@
-from typing import TYPE_CHECKING, List, Optional
+from typing import TYPE_CHECKING, List, Literal, Optional
 
-from fastapi import APIRouter, Body, Depends, Header, HTTPException, Query
+from fastapi import APIRouter, Body, Depends, HTTPException, Query
 
 from letta.orm.errors import NoResultFound
 from letta.schemas.agent import AgentState
 from letta.schemas.block import Block, BlockUpdate, CreateBlock
-from letta.server.rest_api.utils import get_letta_server
+from letta.server.rest_api.dependencies import HeaderParams, get_headers, get_letta_server
 from letta.server.server import SyncServer
 
 if TYPE_CHECKING:
@@ -26,12 +26,16 @@ async def list_blocks(
     limit: Optional[int] = Query(50, description="Number of blocks to return"),
     before: Optional[str] = Query(
         None,
-        description="Cursor for pagination. If provided, returns blocks before this cursor.",
+        description="Block ID cursor for pagination. Returns blocks that come before this block ID in the specified sort order",
     ),
     after: Optional[str] = Query(
         None,
-        description="Cursor for pagination. If provided, returns blocks after this cursor.",
+        description="Block ID cursor for pagination. Returns blocks that come after this block ID in the specified sort order",
     ),
+    order: Literal["asc", "desc"] = Query(
+        "asc", description="Sort order for blocks by creation time. 'asc' for oldest first, 'desc' for newest first"
+    ),
+    order_by: Literal["created_at"] = Query("created_at", description="Field to sort by"),
     label_search: Optional[str] = Query(
         None,
         description=("Search blocks by label. If provided, returns blocks that match this label. This is a full-text search on labels."),
@@ -74,9 +78,9 @@ async def list_blocks(
         description="If set to True, include blocks marked as hidden in the results.",
     ),
     server: SyncServer = Depends(get_letta_server),
-    actor_id: Optional[str] = Header(None, alias="user_id"),  # Extract user_id from header, default to None if not present
+    headers: HeaderParams = Depends(get_headers),
 ):
-    actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
     return await server.block_manager.get_blocks_async(
         actor=actor,
         label=label,
@@ -94,6 +98,7 @@ async def list_blocks(
         connected_to_agents_count_eq=connected_to_agents_count_eq,
         limit=limit,
         after=after,
+        ascending=(order == "asc"),
         show_hidden_blocks=show_hidden_blocks,
     )
 
@@ -101,12 +106,12 @@ async def list_blocks(
 @router.get("/count", response_model=int, operation_id="count_blocks")
 async def count_blocks(
     server: SyncServer = Depends(get_letta_server),
-    actor_id: Optional[str] = Header(None, alias="user_id"),
+    headers: HeaderParams = Depends(get_headers),
 ):
     """
     Count all blocks created by a user.
     """
-    actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
     return await server.block_manager.size_async(actor=actor)
 
 
@@ -114,9 +119,9 @@ async def count_blocks(
 async def create_block(
     create_block: CreateBlock = Body(...),
     server: SyncServer = Depends(get_letta_server),
-    actor_id: Optional[str] = Header(None, alias="user_id"),
+    headers: HeaderParams = Depends(get_headers),
 ):
-    actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
     block = Block(**create_block.model_dump())
     return await server.block_manager.create_or_update_block_async(actor=actor, block=block)
 
@@ -126,9 +131,9 @@ async def modify_block(
     block_id: str,
     block_update: BlockUpdate = Body(...),
     server: SyncServer = Depends(get_letta_server),
-    actor_id: Optional[str] = Header(None, alias="user_id"),
+    headers: HeaderParams = Depends(get_headers),
 ):
-    actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
     return await server.block_manager.update_block_async(block_id=block_id, block_update=block_update, actor=actor)
 
 
@@ -136,9 +141,9 @@ async def modify_block(
 async def delete_block(
     block_id: str,
     server: SyncServer = Depends(get_letta_server),
-    actor_id: Optional[str] = Header(None, alias="user_id"),
+    headers: HeaderParams = Depends(get_headers),
 ):
-    actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
     await server.block_manager.delete_block_async(block_id=block_id, actor=actor)
 
 
@@ -146,9 +151,9 @@ async def delete_block(
 async def retrieve_block(
     block_id: str,
     server: SyncServer = Depends(get_letta_server),
-    actor_id: Optional[str] = Header(None, alias="user_id"),
+    headers: HeaderParams = Depends(get_headers),
 ):
-    actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
     try:
         block = await server.block_manager.get_block_by_id_async(block_id=block_id, actor=actor)
         if block is None:
@@ -161,6 +166,19 @@ async def retrieve_block(
 @router.get("/{block_id}/agents", response_model=List[AgentState], operation_id="list_agents_for_block")
 async def list_agents_for_block(
     block_id: str,
+    before: Optional[str] = Query(
+        None,
+        description="Agent ID cursor for pagination. Returns agents that come before this agent ID in the specified sort order",
+    ),
+    after: Optional[str] = Query(
+        None,
+        description="Agent ID cursor for pagination. Returns agents that come after this agent ID in the specified sort order",
+    ),
+    limit: Optional[int] = Query(50, description="Maximum number of agents to return"),
+    order: Literal["asc", "desc"] = Query(
+        "desc", description="Sort order for agents by creation time. 'asc' for oldest first, 'desc' for newest first"
+    ),
+    order_by: Literal["created_at"] = Query("created_at", description="Field to sort by"),
     include_relationships: list[str] | None = Query(
         None,
         description=(
@@ -170,16 +188,22 @@ async def list_agents_for_block(
         ),
     ),
     server: SyncServer = Depends(get_letta_server),
-    actor_id: Optional[str] = Header(None, alias="user_id"),
+    headers: HeaderParams = Depends(get_headers),
 ):
     """
     Retrieves all agents associated with the specified block.
     Raises a 404 if the block does not exist.
     """
-    actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
     try:
         agents = await server.block_manager.get_agents_for_block_async(
-            block_id=block_id, include_relationships=include_relationships, actor=actor
+            block_id=block_id,
+            before=before,
+            after=after,
+            limit=limit,
+            ascending=(order == "asc"),
+            include_relationships=include_relationships,
+            actor=actor,
         )
         return agents
     except NoResultFound:

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

@@ -2,7 +2,7 @@ from typing import Optional
 
 from fastapi import APIRouter, Depends, Header
 
-from letta.server.rest_api.utils import get_letta_server
+from letta.server.rest_api.dependencies import HeaderParams, get_headers, get_letta_server
 from letta.server.server import SyncServer
 
 router = APIRouter(prefix="/embeddings", tags=["embeddings"])
@@ -11,11 +11,11 @@ router = APIRouter(prefix="/embeddings", tags=["embeddings"])
 @router.get("/total_storage_size", response_model=float, operation_id="get_total_storage_size")
 async def get_embeddings_total_storage_size(
     server: SyncServer = Depends(get_letta_server),
-    actor_id: Optional[str] = Header(None, alias="user_id"),  # Extract user_id from header, default to None if not present
+    headers: HeaderParams = Depends(get_headers),
     storage_unit: Optional[str] = Header("GB", alias="storage_unit"),  # Extract storage unit from header, default to GB
 ):
     """
     Get the total size of all embeddings in the database for a user in the storage unit given.
     """
-    actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
     return await server.passage_manager.estimate_embeddings_size_async(actor=actor, storage_unit=storage_unit)

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

@@ -1,11 +1,10 @@
-import asyncio
 import mimetypes
 import os
 import tempfile
 from pathlib import Path
-from typing import List, Optional
+from typing import List, Literal, Optional
 
-from fastapi import APIRouter, Depends, Header, HTTPException, Query, UploadFile
+from fastapi import APIRouter, Depends, HTTPException, Query, UploadFile
 from starlette import status
 from starlette.responses import Response
 
@@ -27,7 +26,7 @@ from letta.schemas.passage import Passage
 from letta.schemas.source import Source, SourceCreate, SourceUpdate
 from letta.schemas.source_metadata import OrganizationSourcesStats
 from letta.schemas.user import User
-from letta.server.rest_api.utils import get_letta_server
+from letta.server.rest_api.dependencies import HeaderParams, get_headers, get_letta_server
 from letta.server.server import SyncServer
 from letta.services.file_processor.embedder.openai_embedder import OpenAIEmbedder
 from letta.services.file_processor.embedder.pinecone_embedder import PineconeEmbedder
@@ -50,12 +49,12 @@ router = APIRouter(prefix="/folders", tags=["folders"])
 @router.get("/count", response_model=int, operation_id="count_folders")
 async def count_folders(
     server: "SyncServer" = Depends(get_letta_server),
-    actor_id: Optional[str] = Header(None, alias="user_id"),  # Extract user_id from header, default to None if not present
+    headers: HeaderParams = Depends(get_headers),
 ):
     """
     Count all data folders created by a user.
     """
-    actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
     return await server.source_manager.size_async(actor=actor)
 
 
@@ -63,12 +62,12 @@ async def count_folders(
 async def retrieve_folder(
     folder_id: str,
     server: "SyncServer" = Depends(get_letta_server),
-    actor_id: Optional[str] = Header(None, alias="user_id"),  # Extract user_id from header, default to None if not present
+    headers: HeaderParams = Depends(get_headers),
 ):
     """
     Get a folder by ID
     """
-    actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
 
     folder = await server.source_manager.get_source_by_id(source_id=folder_id, actor=actor)
     if not folder:
@@ -76,16 +75,19 @@ async def retrieve_folder(
     return folder
 
 
-@router.get("/name/{folder_name}", response_model=str, operation_id="get_folder_id_by_name")
-async def get_folder_id_by_name(
+@router.get("/name/{folder_name}", response_model=str, operation_id="get_folder_by_name", deprecated=True)
+async def get_folder_by_name(
     folder_name: str,
     server: "SyncServer" = Depends(get_letta_server),
-    actor_id: Optional[str] = Header(None, alias="user_id"),  # Extract user_id from header, default to None if not present
+    headers: HeaderParams = Depends(get_headers),
 ):
     """
-    Get a folder by name
+    **Deprecated**: Please use the list endpoint `GET /v1/folders?name=` instead.
+
+
+    Get a folder by name.
     """
-    actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
 
     folder = await server.source_manager.get_source_by_name(source_name=folder_name, actor=actor)
     if not folder:
@@ -93,10 +95,10 @@ async def get_folder_id_by_name(
     return folder.id
 
 
-@router.get("/metadata", response_model=OrganizationSourcesStats, operation_id="get_folders_metadata")
-async def get_folders_metadata(
+@router.get("/metadata", response_model=OrganizationSourcesStats, operation_id="retrieve_metadata")
+async def retrieve_metadata(
     server: "SyncServer" = Depends(get_letta_server),
-    actor_id: Optional[str] = Header(None, alias="user_id"),
+    headers: HeaderParams = Depends(get_headers),
     include_detailed_per_source_metadata: bool = False,
 ):
     """
@@ -108,7 +110,7 @@ async def get_folders_metadata(
     - Total size of all files
     - Per-source breakdown with file details (file_name, file_size per file) if include_detailed_per_source_metadata is True
     """
-    actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
     return await server.file_manager.get_organization_sources_metadata(
         actor=actor, include_detailed_per_source_metadata=include_detailed_per_source_metadata
     )
@@ -116,26 +118,40 @@ async def get_folders_metadata(
 
 @router.get("/", response_model=List[Folder], operation_id="list_folders")
 async def list_folders(
+    before: Optional[str] = Query(
+        None, description="Folder ID cursor for pagination. Returns folders that come before this folder ID in the specified sort order"
+    ),
+    after: Optional[str] = Query(
+        None, description="Folder ID cursor for pagination. Returns folders that come after this folder ID in the specified sort order"
+    ),
+    limit: Optional[int] = Query(50, description="Maximum number of folders to return"),
+    order: Literal["asc", "desc"] = Query(
+        "asc", description="Sort order for folders by creation time. 'asc' for oldest first, 'desc' for newest first"
+    ),
+    order_by: Literal["created_at"] = Query("created_at", description="Field to sort by"),
+    name: Optional[str] = Query(None, description="Folder name to filter by"),
     server: "SyncServer" = Depends(get_letta_server),
-    actor_id: Optional[str] = Header(None, alias="user_id"),  # Extract user_id from header, default to None if not present
+    headers: HeaderParams = Depends(get_headers),
 ):
     """
     List all data folders created by a user.
     """
-    actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
-    return await server.source_manager.list_sources(actor=actor)
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
+    return await server.source_manager.list_sources(
+        actor=actor, before=before, after=after, limit=limit, ascending=(order == "asc"), name=name
+    )
 
 
 @router.post("/", response_model=Folder, operation_id="create_folder")
 async def create_folder(
     folder_create: SourceCreate,
     server: "SyncServer" = Depends(get_letta_server),
-    actor_id: Optional[str] = Header(None, alias="user_id"),  # Extract user_id from header, default to None if not present
+    headers: HeaderParams = Depends(get_headers),
 ):
     """
     Create a new data folder.
     """
-    actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
 
     # TODO: need to asyncify this
     if not folder_create.embedding_config:
@@ -165,13 +181,13 @@ async def modify_folder(
     folder_id: str,
     folder: SourceUpdate,
     server: "SyncServer" = Depends(get_letta_server),
-    actor_id: Optional[str] = Header(None, alias="user_id"),  # Extract user_id from header, default to None if not present
+    headers: HeaderParams = Depends(get_headers),
 ):
     """
     Update the name or documentation of an existing data folder.
     """
     # TODO: allow updating the handle/embedding config
-    actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
     if not await server.source_manager.get_source_by_id(source_id=folder_id, actor=actor):
         raise HTTPException(status_code=404, detail=f"Folder with id={folder_id} does not exist.")
     return await server.source_manager.update_source(source_id=folder_id, source_update=folder, actor=actor)
@@ -181,12 +197,12 @@ async def modify_folder(
 async def delete_folder(
     folder_id: str,
     server: "SyncServer" = Depends(get_letta_server),
-    actor_id: Optional[str] = Header(None, alias="user_id"),  # Extract user_id from header, default to None if not present
+    headers: HeaderParams = Depends(get_headers),
 ):
     """
     Delete a data folder.
     """
-    actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
     folder = await server.source_manager.get_source_by_id(source_id=folder_id, actor=actor)
     agent_states = await server.source_manager.list_attached_agents(source_id=folder_id, actor=actor)
     files = await server.file_manager.list_files(folder_id, actor)
@@ -221,7 +237,7 @@ async def upload_file_to_folder(
     duplicate_handling: DuplicateFileHandling = Query(DuplicateFileHandling.SUFFIX, description="How to handle duplicate filenames"),
     name: Optional[str] = Query(None, description="Optional custom name to override the uploaded file's name"),
     server: "SyncServer" = Depends(get_letta_server),
-    actor_id: Optional[str] = Header(None, alias="user_id"),
+    headers: HeaderParams = Depends(get_headers),
 ):
     """
     Upload a file to a data folder.
@@ -258,7 +274,7 @@ async def upload_file_to_folder(
             ),
         )
 
-    actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
 
     folder = await server.source_manager.get_source_by_id(source_id=folder_id, actor=actor)
     if folder is None:
@@ -332,58 +348,102 @@ async def upload_file_to_folder(
     return file_metadata
 
 
-@router.get("/{folder_id}/agents", response_model=List[str], operation_id="get_agents_for_folder")
-async def get_agents_for_folder(
+@router.get("/{folder_id}/agents", response_model=List[str], operation_id="list_agents_for_folder")
+async def list_agents_for_folder(
     folder_id: str,
+    before: Optional[str] = Query(
+        None,
+        description="Agent ID cursor for pagination. Returns agents that come before this agent ID in the specified sort order",
+    ),
+    after: Optional[str] = Query(
+        None,
+        description="Agent ID cursor for pagination. Returns agents that come after this agent ID in the specified sort order",
+    ),
+    limit: Optional[int] = Query(50, description="Maximum number of agents to return"),
+    order: Literal["asc", "desc"] = Query(
+        "desc", description="Sort order for agents by creation time. 'asc' for oldest first, 'desc' for newest first"
+    ),
+    order_by: Literal["created_at"] = Query("created_at", description="Field to sort by"),
     server: SyncServer = Depends(get_letta_server),
-    actor_id: Optional[str] = Header(None, alias="user_id"),
+    headers: HeaderParams = Depends(get_headers),
 ):
     """
     Get all agent IDs that have the specified folder attached.
     """
-    actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
-    return await server.source_manager.get_agents_for_source_id(source_id=folder_id, actor=actor)
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
+    return await server.source_manager.get_agents_for_source_id(
+        source_id=folder_id,
+        before=before,
+        after=after,
+        limit=limit,
+        ascending=(order == "asc"),
+        actor=actor,
+    )
 
 
 @router.get("/{folder_id}/passages", response_model=List[Passage], operation_id="list_folder_passages")
 async def list_folder_passages(
     folder_id: str,
-    after: Optional[str] = Query(None, description="Message after which to retrieve the returned messages."),
-    before: Optional[str] = Query(None, description="Message before which to retrieve the returned messages."),
-    limit: int = Query(100, description="Maximum number of messages to retrieve."),
+    before: Optional[str] = Query(
+        None,
+        description="Passage ID cursor for pagination. Returns passages that come before this passage ID in the specified sort order",
+    ),
+    after: Optional[str] = Query(
+        None,
+        description="Passage ID cursor for pagination. Returns passages that come after this passage ID in the specified sort order",
+    ),
+    limit: Optional[int] = Query(100, description="Maximum number of passages to return"),
+    order: Literal["asc", "desc"] = Query(
+        "desc", description="Sort order for passages by creation time. 'asc' for oldest first, 'desc' for newest first"
+    ),
+    order_by: Literal["created_at"] = Query("created_at", description="Field to sort by"),
     server: SyncServer = Depends(get_letta_server),
-    actor_id: Optional[str] = Header(None, alias="user_id"),  # Extract user_id from header, default to None if not present
+    headers: HeaderParams = Depends(get_headers),
 ):
     """
     List all passages associated with a data folder.
     """
-    actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
     return await server.agent_manager.query_source_passages_async(
         actor=actor,
         source_id=folder_id,
         after=after,
         before=before,
         limit=limit,
+        ascending=(order == "asc"),
     )
 
 
 @router.get("/{folder_id}/files", response_model=List[FileMetadata], operation_id="list_folder_files")
 async def list_folder_files(
     folder_id: str,
-    limit: int = Query(1000, description="Number of files to return"),
-    after: Optional[str] = Query(None, description="Pagination cursor to fetch the next set of results"),
+    before: Optional[str] = Query(
+        None,
+        description="File ID cursor for pagination. Returns files that come before this file ID in the specified sort order",
+    ),
+    after: Optional[str] = Query(
+        None,
+        description="File ID cursor for pagination. Returns files that come after this file ID in the specified sort order",
+    ),
+    limit: Optional[int] = Query(1000, description="Maximum number of files to return"),
+    order: Literal["asc", "desc"] = Query(
+        "desc", description="Sort order for files by creation time. 'asc' for oldest first, 'desc' for newest first"
+    ),
+    order_by: Literal["created_at"] = Query("created_at", description="Field to sort by"),
     include_content: bool = Query(False, description="Whether to include full file content"),
     server: "SyncServer" = Depends(get_letta_server),
-    actor_id: Optional[str] = Header(None, alias="user_id"),
+    headers: HeaderParams = Depends(get_headers),
 ):
     """
     List paginated files associated with a data folder.
     """
-    actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
     return await server.file_manager.list_files(
         source_id=folder_id,
-        limit=limit,
+        before=before,
         after=after,
+        limit=limit,
+        ascending=(order == "asc"),
         actor=actor,
         include_content=include_content,
         strip_directory_prefix=True,  # TODO: Reconsider this. This is purely for aesthetics.
@@ -396,12 +456,12 @@ async def list_folder_files(
 #    file_id: str,
 #    include_content: bool = Query(False, description="Whether to include full file content"),
 #    server: "SyncServer" = Depends(get_letta_server),
-#    actor_id: Optional[str] = Header(None, alias="user_id"),
+#    headers: HeaderParams = Depends(get_headers),
 # ):
 #    """
 #    Retrieve metadata for a specific file by its ID.
 #    """
-#    actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
+#    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
 #
 #    # Get file metadata using the file manager
 #    file_metadata = await server.file_manager.get_file_by_id(
@@ -446,12 +506,12 @@ async def delete_file_from_folder(
     folder_id: str,
     file_id: str,
     server: "SyncServer" = Depends(get_letta_server),
-    actor_id: Optional[str] = Header(None, alias="user_id"),  # Extract user_id from header, default to None if not present
+    headers: HeaderParams = Depends(get_headers),
 ):
     """
     Delete a file from a folder.
     """
-    actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
 
     deleted_file = await server.file_manager.delete_file(file_id=file_id, actor=actor)