letta-nightly 0.12.1.dev20251024104217__py3-none-any.whl → 0.13.0.dev20251024223017__py3-none-any.whl

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

@@ -1,12 +1,17 @@
+from datetime import datetime
 from typing import List, Literal, Optional
 
-from fastapi import APIRouter, Body, Depends, HTTPException, Query
-from pydantic import BaseModel
+from fastapi import APIRouter, Body, Depends, Query
+from pydantic import BaseModel, Field
 
-from letta.orm.errors import NoResultFound
-from letta.schemas.archive import Archive as PydanticArchive
+from letta import AgentState
+from letta.schemas.agent import AgentRelationships
+from letta.schemas.archive import Archive as PydanticArchive, ArchiveBase
+from letta.schemas.embedding_config import EmbeddingConfig
+from letta.schemas.passage import Passage as PydanticPassage
 from letta.server.rest_api.dependencies import HeaderParams, get_headers, get_letta_server
 from letta.server.server import SyncServer
+from letta.validators import AgentId, ArchiveId, PassageId
 
 router = APIRouter(prefix="/archives", tags=["archives"])
 
@@ -18,6 +23,7 @@ class ArchiveCreateRequest(BaseModel):
     """
 
     name: str
+    embedding_config: EmbeddingConfig = Field(..., description="Embedding configuration for the archive")
     description: Optional[str] = None
 
 
@@ -40,15 +46,13 @@ async def create_archive(
     """
     Create a new archive.
     """
-    try:
-        actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
-        return await server.archive_manager.create_archive_async(
-            name=archive.name,
-            description=archive.description,
-            actor=actor,
-        )
-    except Exception as e:
-        raise HTTPException(status_code=500, detail=str(e))
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
+    return await server.archive_manager.create_archive_async(
+        name=archive.name,
+        embedding_config=archive.embedding_config,
+        description=archive.description,
+        actor=actor,
+    )
 
 
 @router.get("/", response_model=List[PydanticArchive], operation_id="list_archives")
@@ -65,6 +69,7 @@ async def list_archives(
     order: Literal["asc", "desc"] = Query(
         "desc", description="Sort order for archives 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="Filter by archive name (exact match)"),
     agent_id: Optional[str] = Query(None, description="Only archives attached to this agent ID"),
     server: "SyncServer" = Depends(get_letta_server),
@@ -73,25 +78,38 @@ async def list_archives(
     """
     Get a list of all archives for the current organization with optional filters and pagination.
     """
-    try:
-        actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
-        archives = await server.archive_manager.list_archives_async(
-            actor=actor,
-            before=before,
-            after=after,
-            limit=limit,
-            ascending=(order == "asc"),
-            name=name,
-            agent_id=agent_id,
-        )
-        return archives
-    except Exception as e:
-        raise HTTPException(status_code=500, detail=str(e))
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
+    archives = await server.archive_manager.list_archives_async(
+        actor=actor,
+        before=before,
+        after=after,
+        limit=limit,
+        ascending=(order == "asc"),
+        name=name,
+        agent_id=agent_id,
+    )
+    return archives
+
+
+@router.get("/{archive_id}", response_model=PydanticArchive, operation_id="get_archive_by_id")
+async def get_archive_by_id(
+    archive_id: ArchiveId,
+    server: "SyncServer" = Depends(get_letta_server),
+    headers: HeaderParams = Depends(get_headers),
+):
+    """
+    Get a single archive by its ID.
+    """
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
+    return await server.archive_manager.get_archive_by_id_async(
+        archive_id=archive_id,
+        actor=actor,
+    )
 
 
 @router.patch("/{archive_id}", response_model=PydanticArchive, operation_id="modify_archive")
 async def modify_archive(
-    archive_id: str,
+    archive_id: ArchiveId,
     archive: ArchiveUpdateRequest = Body(...),
     server: "SyncServer" = Depends(get_letta_server),
     headers: HeaderParams = Depends(get_headers),
@@ -99,15 +117,84 @@ async def modify_archive(
     """
     Update an existing archive's name and/or description.
     """
-    try:
-        actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
-        return await server.archive_manager.update_archive_async(
-            archive_id=archive_id,
-            name=archive.name,
-            description=archive.description,
-            actor=actor,
-        )
-    except NoResultFound as e:
-        raise HTTPException(status_code=404, detail=str(e))
-    except Exception as e:
-        raise HTTPException(status_code=500, detail=str(e))
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
+    return await server.archive_manager.update_archive_async(
+        archive_id=archive_id,
+        name=archive.name,
+        description=archive.description,
+        actor=actor,
+    )
+
+
+@router.delete("/{archive_id}", response_model=PydanticArchive, operation_id="delete_archive")
+async def delete_archive(
+    archive_id: ArchiveId,
+    server: "SyncServer" = Depends(get_letta_server),
+    headers: HeaderParams = Depends(get_headers),
+):
+    """
+    Delete an archive by its ID.
+    """
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
+    return await server.archive_manager.delete_archive_async(
+        archive_id=archive_id,
+        actor=actor,
+    )
+
+
+@router.get("/{archive_id}/agents", response_model=List[AgentState], operation_id="list_agents_for_archive")
+async def list_agents_for_archive(
+    archive_id: ArchiveId,
+    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"
+    ),
+    include: List[AgentRelationships] = Query(
+        [],
+        description=("Specify which relational fields to include in the response. No relationships are included by default."),
+    ),
+    server: "SyncServer" = Depends(get_letta_server),
+    headers: HeaderParams = Depends(get_headers),
+):
+    """
+    Get a list of agents that have access to an archive with pagination support.
+    """
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
+    return await server.archive_manager.get_agents_for_archive_async(
+        archive_id=archive_id,
+        actor=actor,
+        before=before,
+        after=after,
+        limit=limit,
+        include=include,
+        ascending=(order == "asc"),
+    )
+
+
+@router.delete("/{archive_id}/passages/{passage_id}", status_code=204, operation_id="delete_passage_from_archive")
+async def delete_passage_from_archive(
+    archive_id: ArchiveId,
+    passage_id: PassageId,
+    server: "SyncServer" = Depends(get_letta_server),
+    headers: HeaderParams = Depends(get_headers),
+):
+    """
+    Delete a passage from an archive.
+
+    This permanently removes the passage from both the database and vector storage (if applicable).
+    """
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
+    await server.archive_manager.delete_passage_from_archive_async(
+        archive_id=archive_id,
+        passage_id=passage_id,
+        actor=actor,
+    )
+    return None

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

@@ -3,10 +3,12 @@ from typing import TYPE_CHECKING, List, Literal, Optional
 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.schemas.agent import AgentRelationships, AgentState
+from letta.schemas.block import BaseBlock, Block, BlockUpdate, CreateBlock
 from letta.server.rest_api.dependencies import HeaderParams, get_headers, get_letta_server
 from letta.server.server import SyncServer
+from letta.utils import is_1_0_sdk_version
+from letta.validators import BlockId
 
 if TYPE_CHECKING:
     pass
@@ -128,7 +130,7 @@ async def create_block(
 
 @router.patch("/{block_id}", response_model=Block, operation_id="modify_block")
 async def modify_block(
-    block_id: str,
+    block_id: BlockId,
     block_update: BlockUpdate = Body(...),
     server: SyncServer = Depends(get_letta_server),
     headers: HeaderParams = Depends(get_headers),
@@ -139,7 +141,7 @@ async def modify_block(
 
 @router.delete("/{block_id}", operation_id="delete_block")
 async def delete_block(
-    block_id: str,
+    block_id: BlockId,
     server: SyncServer = Depends(get_letta_server),
     headers: HeaderParams = Depends(get_headers),
 ):
@@ -149,7 +151,7 @@ async def delete_block(
 
 @router.get("/{block_id}", response_model=Block, operation_id="retrieve_block")
 async def retrieve_block(
-    block_id: str,
+    block_id: BlockId,
     server: SyncServer = Depends(get_letta_server),
     headers: HeaderParams = Depends(get_headers),
 ):
@@ -162,7 +164,7 @@ 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,
+    block_id: BlockId,
     before: Optional[str] = Query(
         None,
         description="Agent ID cursor for pagination. Returns agents that come before this agent ID in the specified sort order",
@@ -182,8 +184,13 @@ async def list_agents_for_block(
             "Specify which relational fields (e.g., 'tools', 'sources', 'memory') to include in the response. "
             "If not provided, all relationships are loaded by default. "
             "Using this can optimize performance by reducing unnecessary joins."
+            "This is a legacy parameter, and no longer supported after 1.0.0 SDK versions."
         ),
     ),
+    include: List[AgentRelationships] = Query(
+        [],
+        description=("Specify which relational fields to include in the response. No relationships are included by default."),
+    ),
     server: SyncServer = Depends(get_letta_server),
     headers: HeaderParams = Depends(get_headers),
 ):
@@ -192,6 +199,8 @@ async def list_agents_for_block(
     Raises a 404 if the block does not exist.
     """
     actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
+    if include_relationships is None and is_1_0_sdk_version(headers):
+        include_relationships = []  # don't default include all if using new SDK version
     agents = await server.block_manager.get_agents_for_block_async(
         block_id=block_id,
         before=before,
@@ -199,6 +208,45 @@ async def list_agents_for_block(
         limit=limit,
         ascending=(order == "asc"),
         include_relationships=include_relationships,
+        include=include,
         actor=actor,
     )
     return agents
+
+
+@router.patch("/{block_id}/identities/attach/{identity_id}", response_model=Block, operation_id="attach_identity_to_block")
+async def attach_identity_to_block(
+    identity_id: str,
+    block_id: BlockId,
+    server: SyncServer = Depends(get_letta_server),
+    headers: HeaderParams = Depends(get_headers),
+):
+    """
+    Attach an identity to a block.
+    """
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
+    await server.identity_manager.attach_block_async(
+        identity_id=identity_id,
+        block_id=block_id,
+        actor=actor,
+    )
+    return await server.block_manager.get_block_by_id_async(block_id=block_id, actor=actor)
+
+
+@router.patch("/{block_id}/identities/detach/{identity_id}", response_model=Block, operation_id="detach_identity_from_block")
+async def detach_identity_from_block(
+    identity_id: str,
+    block_id: BlockId,
+    server: SyncServer = Depends(get_letta_server),
+    headers: HeaderParams = Depends(get_headers),
+):
+    """
+    Detach an identity from a block.
+    """
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
+    await server.identity_manager.detach_block_async(
+        identity_id=identity_id,
+        block_id=block_id,
+        actor=actor,
+    )
+    return await server.block_manager.get_block_by_id_async(block_id=block_id, actor=actor)

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

@@ -0,0 +1,146 @@
+from typing import Optional, Union
+
+from fastapi import APIRouter, Body, Depends
+from fastapi.responses import StreamingResponse
+from openai.types.chat import ChatCompletion
+from openai.types.chat.chat_completion_message_param import ChatCompletionMessageParam
+from pydantic import BaseModel, Field
+
+from letta.errors import LettaInvalidArgumentError
+from letta.log import get_logger
+from letta.schemas.enums import MessageRole
+from letta.schemas.letta_request import LettaStreamingRequest
+from letta.schemas.message import MessageCreate
+from letta.server.rest_api.dependencies import HeaderParams, get_headers, get_letta_server
+from letta.server.server import SyncServer
+from letta.services.streaming_service import StreamingService
+
+logger = get_logger(__name__)
+
+router = APIRouter(tags=["chat"])
+
+
+class ChatCompletionRequest(BaseModel):
+    """OpenAI-compatible chat completion request - exactly matching OpenAI's schema."""
+
+    model: str = Field(..., description="ID of the model to use")
+    messages: list[ChatCompletionMessageParam] = Field(..., description="Messages comprising the conversation so far")
+
+    # optional parameters
+    temperature: Optional[float] = Field(None, ge=0, le=2, description="Sampling temperature")
+    top_p: Optional[float] = Field(None, ge=0, le=1, description="Nucleus sampling parameter")
+    n: Optional[int] = Field(1, ge=1, description="Number of chat completion choices to generate")
+    stream: Optional[bool] = Field(False, description="Whether to stream back partial progress")
+    stop: Optional[Union[str, list[str]]] = Field(None, description="Sequences where the API will stop generating")
+    max_tokens: Optional[int] = Field(None, description="Maximum number of tokens to generate")
+    presence_penalty: Optional[float] = Field(None, ge=-2, le=2, description="Presence penalty")
+    frequency_penalty: Optional[float] = Field(None, ge=-2, le=2, description="Frequency penalty")
+    user: Optional[str] = Field(None, description="A unique identifier representing your end-user")
+
+
+async def _handle_chat_completion(
+    request: ChatCompletionRequest,
+    server: SyncServer,
+    headers: HeaderParams,
+) -> Union[ChatCompletion, StreamingResponse]:
+    """
+    Internal handler for chat completion logic.
+
+    Args:
+        request: OpenAI-compatible chat completion request
+        server: Letta server instance
+        headers: Request headers with user info
+
+    Returns:
+        Streaming or non-streaming chat completion response
+    """
+    if request.user:
+        actor = await server.user_manager.get_actor_or_default_async(actor_id=request.user)
+    else:
+        actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
+
+    resolved_agent_id = request.model
+    if not resolved_agent_id.startswith("agent-"):
+        raise LettaInvalidArgumentError(
+            f"For this endpoint, the 'model' field should contain an agent ID (format: 'agent-...'). Received: '{resolved_agent_id}'",
+            argument_name="model",
+        )
+    await server.agent_manager.validate_agent_exists_async(resolved_agent_id, actor)
+
+    # convert OpenAI messages to Letta MessageCreate format
+    # NOTE: we only process the last user message
+    if len(request.messages) > 1:
+        logger.warning(
+            f"Chat completions endpoint received {len(request.messages)} messages. "
+            "Letta maintains conversation state internally, so only the last user message will be processed. "
+            "Previous messages are already stored in the agent's memory."
+        )
+
+    last_user_message = None
+    for msg in reversed(request.messages):
+        role = msg.get("role", "user")
+        if role == "user":
+            last_user_message = msg
+            break
+
+    if not last_user_message:
+        raise LettaInvalidArgumentError(
+            "No user message found in the request. Please include at least one message with role='user'.",
+            argument_name="messages",
+        )
+
+    letta_messages = [
+        MessageCreate(
+            role=MessageRole.user,
+            content=last_user_message.get("content", ""),
+        )
+    ]
+
+    letta_request = LettaStreamingRequest(
+        messages=letta_messages,
+        stream_tokens=True,
+    )
+
+    if request.stream:
+        streaming_service = StreamingService(server)
+        return await streaming_service.create_agent_stream_openai_chat_completions(
+            agent_id=resolved_agent_id,
+            actor=actor,
+            request=letta_request,
+        )
+    else:
+        raise LettaInvalidArgumentError(
+            "Non-streaming chat completions not yet implemented. Please set stream=true.",
+            argument_name="stream",
+        )
+
+
+@router.post(
+    "/chat/completions",
+    response_model=ChatCompletion,
+    responses={
+        200: {
+            "description": "Successful response",
+            "content": {
+                "application/json": {"schema": {"$ref": "#/components/schemas/ChatCompletion"}},
+                "text/event-stream": {"description": "Server-Sent Events stream (when stream=true)"},
+            },
+        }
+    },
+    operation_id="create_chat_completion",
+)
+async def create_chat_completion(
+    request: ChatCompletionRequest = Body(...),
+    server: SyncServer = Depends(get_letta_server),
+    headers: HeaderParams = Depends(get_headers),
+) -> Union[ChatCompletion, StreamingResponse]:
+    """
+    Create a chat completion using a Letta agent (OpenAI-compatible).
+
+    This endpoint provides full OpenAI API compatibility. The agent is selected based on:
+    - The 'model' parameter in the request (should contain an agent ID in format 'agent-...')
+
+    When streaming is enabled (stream=true), the response will be Server-Sent Events
+    with ChatCompletionChunk objects.
+    """
+    return await _handle_chat_completion(request, server, headers)