Platform for stateful agents: AI with advanced memory that can learn and self-improve over time.
feat: Support basic upload/querying on tpuf [LET-3465] (#4255)
Matthew Zhou651671cb8389
diff --git a/alembic/versions/068588268b02_add_vector_db_provider_to_archives_table.py b/alembic/versions/068588268b02_add_vector_db_provider_to_archives_table.pynew file mode 100644index 000000000..f7f0dca70--- /dev/null+++ b/alembic/versions/068588268b02_add_vector_db_provider_to_archives_table.py@@ -0,0 +1,60 @@+"""Add vector_db_provider to archives table++Revision ID: 068588268b02+Revises: d5103ee17ed5+Create Date: 2025-08-27 13:16:29.428231++"""++from typing import Sequence, Union++import sqlalchemy as sa++from alembic import op+from letta.settings import settings++# revision identifiers, used by Alembic.+revision: str = "068588268b02"+down_revision: Union[str, None] = "887a4367b560"+branch_labels: Union[str, Sequence[str], None] = None+depends_on: Union[str, Sequence[str], None] = None+++def upgrade() -> None:+ # ### commands auto generated by Alembic - please adjust! ###+ if settings.letta_pg_uri_no_default:+ # PostgreSQL - use enum type+ vectordbprovider = sa.Enum("NATIVE", "TPUF", name="vectordbprovider")+ vectordbprovider.create(op.get_bind(), checkfirst=True)++ # Add column as nullable first+ op.add_column("archives", sa.Column("vector_db_provider", vectordbprovider, nullable=True))++ # Backfill existing rows with NATIVE+ op.execute("UPDATE archives SET vector_db_provider = 'NATIVE' WHERE vector_db_provider IS NULL")++ # Make column non-nullable+ op.alter_column("archives", "vector_db_provider", nullable=False)+ else:+ # SQLite - use string type+ # Add column as nullable first+ op.add_column("archives", sa.Column("vector_db_provider", sa.String(), nullable=True))++ # Backfill existing rows with NATIVE+ op.execute("UPDATE archives SET vector_db_provider = 'NATIVE' WHERE vector_db_provider IS NULL")++ # For SQLite, we need to recreate the table to make column non-nullable+ # This is a limitation of SQLite ALTER TABLE+ # For simplicity, we'll leave it nullable in SQLite+ # ### end Alembic commands ###+++def downgrade() -> None:+ # ### commands auto generated by Alembic - please adjust! ###+ op.drop_column("archives", "vector_db_provider")++ if settings.letta_pg_uri_no_default:+ # Drop enum type for PostgreSQL+ vectordbprovider = sa.Enum("NATIVE", "TPUF", name="vectordbprovider")+ vectordbprovider.drop(op.get_bind(), checkfirst=True)+ # ### end Alembic commands ###diff --git a/letta/agents/voice_agent.py b/letta/agents/voice_agent.pyindex 3b00dfaee..5959fed78 100644--- a/letta/agents/voice_agent.py+++ b/letta/agents/voice_agent.py@@ -484,7 +484,7 @@ class VoiceAgent(BaseAgent):if start_date and end_date and start_date > end_date:start_date, end_date = end_date, start_date- archival_results = await self.agent_manager.list_passages_async(+ archival_results = await self.agent_manager.query_agent_passages_async(actor=self.actor,agent_id=self.agent_id,query_text=archival_query,diff --git a/letta/functions/function_sets/base.py b/letta/functions/function_sets/base.pyindex d0e2e94c4..9fcb2fdbe 100644--- a/letta/functions/function_sets/base.py+++ b/letta/functions/function_sets/base.py@@ -107,7 +107,7 @@ async def archival_memory_search(self: "Agent", query: str, page: Optional[int]try:# Get results using passage manager- all_results = await self.agent_manager.list_passages_async(+ all_results = await self.agent_manager.query_agent_passages_async(actor=self.user,agent_id=self.agent_state.id,query_text=query,diff --git a/letta/helpers/tpuf_client.py b/letta/helpers/tpuf_client.pynew file mode 100644index 000000000..47edf568a--- /dev/null+++ b/letta/helpers/tpuf_client.py@@ -0,0 +1,276 @@+"""Turbopuffer utilities for archival memory storage."""++import logging+from datetime import datetime, timezone+from typing import Any, Dict, List, Optional, Tuple++from letta.otel.tracing import trace_method+from letta.schemas.passage import Passage as PydanticPassage+from letta.settings import settings++logger = logging.getLogger(__name__)+++def should_use_tpuf() -> bool:+ return bool(settings.use_tpuf) and bool(settings.tpuf_api_key)+++class TurbopufferClient:+ """Client for managing archival memory with Turbopuffer vector database."""++ def __init__(self, api_key: str = None, region: str = None):+ """Initialize Turbopuffer client."""+ self.api_key = api_key or settings.tpuf_api_key+ self.region = region or settings.tpuf_region++ if not self.api_key:+ raise ValueError("Turbopuffer API key not provided")++ @trace_method+ def _get_namespace_name(self, archive_id: str) -> str:+ """Get namespace name for a specific archive."""+ # use archive_id as namespace to isolate different archives' memories+ # append environment suffix to namespace for isolation if environment is set+ environment = settings.environment+ if environment:+ namespace_name = f"{archive_id}_{environment.lower()}"+ else:+ namespace_name = archive_id+ return namespace_name++ @trace_method+ async def insert_archival_memories(+ self,+ archive_id: str,+ text_chunks: List[str],+ embeddings: List[List[float]],+ passage_ids: List[str],+ organization_id: str,+ tags: Optional[List[str]] = None,+ created_at: Optional[datetime] = None,+ ) -> List[PydanticPassage]:+ """Insert passages into Turbopuffer.++ Args:+ archive_id: ID of the archive+ text_chunks: List of text chunks to store+ embeddings: List of embedding vectors corresponding to text chunks+ passage_ids: List of passage IDs (must match 1:1 with text_chunks)+ organization_id: Organization ID for the passages+ tags: Optional list of tags to attach to all passages+ created_at: Optional timestamp for retroactive entries (defaults to current UTC time)++ Returns:+ List of PydanticPassage objects that were inserted+ """+ from turbopuffer import AsyncTurbopuffer++ namespace_name = self._get_namespace_name(archive_id)++ # handle timestamp - ensure UTC+ if created_at is None:+ timestamp = datetime.now(timezone.utc)+ else:+ # ensure the provided timestamp is timezone-aware and in UTC+ if created_at.tzinfo is None:+ # assume UTC if no timezone provided+ timestamp = created_at.replace(tzinfo=timezone.utc)+ else:+ # convert to UTC if in different timezone+ timestamp = created_at.astimezone(timezone.utc)++ # passage_ids must be provided for dual-write consistency+ if not passage_ids:+ raise ValueError("passage_ids must be provided for Turbopuffer insertion")+ if len(passage_ids) != len(text_chunks):+ raise ValueError(f"passage_ids length ({len(passage_ids)}) must match text_chunks length ({len(text_chunks)})")+ if len(passage_ids) != len(embeddings):+ raise ValueError(f"passage_ids length ({len(passage_ids)}) must match embeddings length ({len(embeddings)})")++ # prepare column-based data for turbopuffer - optimized for batch insert+ ids = []+ vectors = []+ texts = []+ organization_ids = []+ archive_ids = []+ created_ats = []+ passages = []++ # prepare tag columns+ tag_columns = {tag: [] for tag in (tags or [])}++ for idx, (text, embedding) in enumerate(zip(text_chunks, embeddings)):+ passage_id = passage_ids[idx]++ # append to columns+ ids.append(passage_id)+ vectors.append(embedding)+ texts.append(text)+ organization_ids.append(organization_id)+ archive_ids.append(archive_id)+ created_ats.append(timestamp)++ # append tag values+ for tag in tag_columns:+ tag_columns[tag].append(True)++ # Create PydanticPassage object+ passage = PydanticPassage(+ id=passage_id,+ text=text,+ organization_id=organization_id,+ archive_id=archive_id,+ created_at=timestamp,+ metadata_={},+ embedding=embedding,+ embedding_config=None, # Will be set by caller if needed+ )+ passages.append(passage)++ # build column-based upsert data+ upsert_columns = {+ "id": ids,+ "vector": vectors,+ "text": texts,+ "organization_id": organization_ids,+ "archive_id": archive_ids,+ "created_at": created_ats,+ }++ # add tag columns if any+ upsert_columns.update(tag_columns)++ try:+ # Use AsyncTurbopuffer as a context manager for proper resource cleanup+ async with AsyncTurbopuffer(api_key=self.api_key, region=self.region) as client:+ namespace = client.namespace(namespace_name)+ # turbopuffer recommends column-based writes for performance+ await namespace.write(upsert_columns=upsert_columns, distance_metric="cosine_distance")+ logger.info(f"Successfully inserted {len(ids)} passages to Turbopuffer for archive {archive_id}")+ return passages++ except Exception as e:+ logger.error(f"Failed to insert passages to Turbopuffer: {e}")+ # check if it's a duplicate ID error+ if "duplicate" in str(e).lower():+ logger.error("Duplicate passage IDs detected in batch")+ raise++ @trace_method+ async def query_passages(+ self, archive_id: str, query_embedding: List[float], top_k: int = 10, filters: Optional[Dict[str, Any]] = None+ ) -> List[Tuple[PydanticPassage, float]]:+ """Query passages from Turbopuffer."""+ from turbopuffer import AsyncTurbopuffer++ namespace_name = self._get_namespace_name(archive_id)++ try:+ async with AsyncTurbopuffer(api_key=self.api_key, region=self.region) as client:+ namespace = client.namespace(namespace_name)++ # build filter conditions+ filter_conditions = []+ if filters:+ for key, value in filters.items():+ filter_conditions.append((key, "Eq", value))++ query_params = {+ "rank_by": ("vector", "ANN", query_embedding),+ "top_k": top_k,+ "include_attributes": ["text", "organization_id", "archive_id", "created_at"],+ }++ if filter_conditions:+ query_params["filters"] = ("And", filter_conditions) if len(filter_conditions) > 1 else filter_conditions[0]++ result = await namespace.query(**query_params)++ # convert results back to passages+ passages_with_scores = []+ # Turbopuffer returns a NamespaceQueryResponse with a rows attribute+ for row in result.rows:+ # Build metadata including any filter conditions that were applied+ metadata = {}+ if filters:+ metadata["applied_filters"] = filters++ # Create a passage with minimal fields - embeddings are not returned from Turbopuffer+ passage = PydanticPassage(+ id=row.id,+ text=getattr(row, "text", ""),+ organization_id=getattr(row, "organization_id", None),+ archive_id=archive_id, # use the archive_id from the query+ created_at=getattr(row, "created_at", None),+ metadata_=metadata, # Include filter conditions in metadata+ # Set required fields to empty/default values since we don't store embeddings+ embedding=[], # Empty embedding since we don't return it from Turbopuffer+ embedding_config=None, # No embedding config needed for retrieved passages+ )+ # turbopuffer returns distance in $dist attribute, convert to similarity score+ distance = getattr(row, "$dist", 0.0)+ score = 1.0 - distance+ passages_with_scores.append((passage, score))++ return passages_with_scores++ except Exception as e:+ logger.error(f"Failed to query passages from Turbopuffer: {e}")+ raise++ @trace_method+ async def delete_passage(self, archive_id: str, passage_id: str) -> bool:+ """Delete a passage from Turbopuffer."""+ from turbopuffer import AsyncTurbopuffer++ namespace_name = self._get_namespace_name(archive_id)++ try:+ async with AsyncTurbopuffer(api_key=self.api_key, region=self.region) as client:+ namespace = client.namespace(namespace_name)+ # Use write API with deletes parameter as per Turbopuffer docs+ await namespace.write(deletes=[passage_id])+ logger.info(f"Successfully deleted passage {passage_id} from Turbopuffer archive {archive_id}")+ return True+ except Exception as e:+ logger.error(f"Failed to delete passage from Turbopuffer: {e}")+ raise++ @trace_method+ async def delete_passages(self, archive_id: str, passage_ids: List[str]) -> bool:+ """Delete multiple passages from Turbopuffer."""+ from turbopuffer import AsyncTurbopuffer++ if not passage_ids:+ return True++ namespace_name = self._get_namespace_name(archive_id)++ try:+ async with AsyncTurbopuffer(api_key=self.api_key, region=self.region) as client:+ namespace = client.namespace(namespace_name)+ # Use write API with deletes parameter as per Turbopuffer docs+ await namespace.write(deletes=passage_ids)+ logger.info(f"Successfully deleted {len(passage_ids)} passages from Turbopuffer archive {archive_id}")+ return True+ except Exception as e:+ logger.error(f"Failed to delete passages from Turbopuffer: {e}")+ raise++ @trace_method+ async def delete_all_passages(self, archive_id: str) -> bool:+ """Delete all passages for an archive from Turbopuffer."""+ from turbopuffer import AsyncTurbopuffer++ namespace_name = self._get_namespace_name(archive_id)++ try:+ async with AsyncTurbopuffer(api_key=self.api_key, region=self.region) as client:+ namespace = client.namespace(namespace_name)+ # Turbopuffer has a delete_all() method on namespace+ await namespace.delete_all()+ logger.info(f"Successfully deleted all passages for archive {archive_id}")+ return True+ except Exception as e:+ logger.error(f"Failed to delete all passages from Turbopuffer: {e}")+ raisediff --git a/letta/orm/archive.py b/letta/orm/archive.pyindex 67badc013..e94fda407 100644--- a/letta/orm/archive.py+++ b/letta/orm/archive.py@@ -2,12 +2,13 @@ import uuidfrom datetime import datetime, timezonefrom typing import TYPE_CHECKING, List, Optional-from sqlalchemy import JSON, Index, String+from sqlalchemy import JSON, Enum, Index, Stringfrom sqlalchemy.orm import Mapped, mapped_column, relationshipfrom letta.orm.mixins import OrganizationMixinfrom letta.orm.sqlalchemy_base import SqlalchemyBasefrom letta.schemas.archive import Archive as PydanticArchive+from letta.schemas.enums import VectorDBProviderfrom letta.settings import DatabaseChoice, settingsif TYPE_CHECKING:@@ -38,6 +39,12 @@ class Archive(SqlalchemyBase, OrganizationMixin):# archive-specific fieldsname: Mapped[str] = mapped_column(String, nullable=False, doc="The name of the archive")description: Mapped[Optional[str]] = mapped_column(String, nullable=True, doc="A description of the archive")+ vector_db_provider: Mapped[VectorDBProvider] = mapped_column(+ Enum(VectorDBProvider),+ nullable=False,+ default=VectorDBProvider.NATIVE,+ doc="The vector database provider used for this archive's passages",+ )metadata_: Mapped[Optional[dict]] = mapped_column(JSON, nullable=True, doc="Additional metadata for the archive")# relationshipsdiff --git a/letta/schemas/archive.py b/letta/schemas/archive.pyindex 965708bba..55727e92f 100644--- a/letta/schemas/archive.py+++ b/letta/schemas/archive.py@@ -3,6 +3,7 @@ from typing import Dict, Optionalfrom pydantic import Field+from letta.schemas.enums import VectorDBProviderfrom letta.schemas.letta_base import OrmMetadataBase@@ -12,6 +13,9 @@ class ArchiveBase(OrmMetadataBase):name: str = Field(..., description="The name of the archive")description: Optional[str] = Field(None, description="A description of the archive")organization_id: str = Field(..., description="The organization this archive belongs to")+ vector_db_provider: VectorDBProvider = Field(+ default=VectorDBProvider.NATIVE, description="The vector database provider used for this archive's passages"+ )metadata: Optional[Dict] = Field(default_factory=dict, validation_alias="metadata_", description="Additional metadata")diff --git a/letta/schemas/enums.py b/letta/schemas/enums.pyindex de4a48ecb..a9d1f320c 100644--- a/letta/schemas/enums.py+++ b/letta/schemas/enums.py@@ -171,3 +171,10 @@ class StepStatus(str, Enum):SUCCESS = "success"FAILED = "failed"CANCELLED = "cancelled"+++class VectorDBProvider(str, Enum):+ """Supported vector database providers for archival memory"""++ NATIVE = "native"+ TPUF = "tpuf"diff --git a/letta/schemas/memory.py b/letta/schemas/memory.pyindex 802f2292b..ec4c7ebb0 100644--- a/letta/schemas/memory.py+++ b/letta/schemas/memory.py@@ -1,5 +1,6 @@import asyncioimport logging+from datetime import datetimefrom typing import TYPE_CHECKING, List, Optionalfrom jinja2 import Template, TemplateSyntaxError@@ -325,3 +326,5 @@ class RecallMemorySummary(BaseModel):class CreateArchivalMemory(BaseModel):text: str = Field(..., description="Text to write to archival memory.")+ tags: Optional[List[str]] = Field(None, description="Optional list of tags to attach to the memory.")+ created_at: Optional[datetime] = Field(None, description="Optional timestamp for the memory (defaults to current UTC time).")diff --git a/letta/server/rest_api/routers/v1/agents.py b/letta/server/rest_api/routers/v1/agents.pyindex 313ee0bec..d9c2b3c86 100644--- a/letta/server/rest_api/routers/v1/agents.py+++ b/letta/server/rest_api/routers/v1/agents.py@@ -34,7 +34,7 @@ from letta.schemas.letta_request import LettaAsyncRequest, LettaRequest, LettaStfrom letta.schemas.letta_response import LettaResponsefrom letta.schemas.memory import ContextWindowOverview, CreateArchivalMemory, Memoryfrom letta.schemas.message import MessageCreate-from letta.schemas.passage import Passage, PassageUpdate+from letta.schemas.passage import Passagefrom letta.schemas.run import Runfrom letta.schemas.source import Sourcefrom letta.schemas.tool import Tool@@ -954,22 +954,9 @@ async def create_passage("""actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)- return await server.insert_archival_memory_async(agent_id=agent_id, memory_contents=request.text, actor=actor)--[email protected]("/{agent_id}/archival-memory/{memory_id}", response_model=list[Passage], operation_id="modify_passage")-def modify_passage(- agent_id: str,- memory_id: str,- passage: PassageUpdate = Body(...),- server: "SyncServer" = Depends(get_letta_server),- actor_id: str | None = Header(None, alias="user_id"), # Extract user_id from header, default to None if not present-):- """- Modify a memory in the agent's archival memory store.- """- actor = server.user_manager.get_user_or_default(user_id=actor_id)- return server.modify_archival_memory(agent_id=agent_id, memory_id=memory_id, passage=passage, actor=actor)+ return await server.insert_archival_memory_async(+ agent_id=agent_id, memory_contents=request.text, actor=actor, tags=request.tags, created_at=request.created_at+ )# TODO(ethan): query or path parameter for memory_id?diff --git a/letta/server/rest_api/routers/v1/folders.py b/letta/server/rest_api/routers/v1/folders.pyindex d72d8dddc..dcf984746 100644--- a/letta/server/rest_api/routers/v1/folders.py+++ b/letta/server/rest_api/routers/v1/folders.py@@ -351,7 +351,7 @@ async def list_folder_passages(List all passages associated with a data folder."""actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)- return await server.agent_manager.list_passages_async(+ return await server.agent_manager.query_source_passages_async(actor=actor,source_id=folder_id,after=after,diff --git a/letta/server/rest_api/routers/v1/sources.py b/letta/server/rest_api/routers/v1/sources.pyindex 3bfbb9d27..c9d554072 100644--- a/letta/server/rest_api/routers/v1/sources.py+++ b/letta/server/rest_api/routers/v1/sources.py@@ -349,7 +349,7 @@ async def list_source_passages(List all passages associated with a data source."""actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)- return await server.agent_manager.list_passages_async(+ return await server.agent_manager.query_source_passages_async(actor=actor,source_id=source_id,after=after,diff --git a/letta/server/server.py b/letta/server/server.pyindex 358f95069..1f2a92255 100644--- a/letta/server/server.py+++ b/letta/server/server.py@@ -52,7 +52,7 @@ from letta.schemas.letta_stop_reason import LettaStopReason, StopReasonTypefrom letta.schemas.llm_config import LLMConfigfrom letta.schemas.memory import ArchivalMemorySummary, Memory, RecallMemorySummaryfrom letta.schemas.message import Message, MessageCreate, MessageUpdate-from letta.schemas.passage import Passage, PassageUpdate+from letta.schemas.passage import Passagefrom letta.schemas.pip_requirement import PipRequirementfrom letta.schemas.providers import (AnthropicProvider,@@ -1114,7 +1114,7 @@ class SyncServer(Server):ascending: Optional[bool] = True,) -> List[Passage]:# iterate over records- records = await self.agent_manager.list_agent_passages_async(+ records = await self.agent_manager.query_agent_passages_async(actor=actor,agent_id=agent_id,after=after,@@ -1125,18 +1125,18 @@ class SyncServer(Server):)return records- async def insert_archival_memory_async(self, agent_id: str, memory_contents: str, actor: User) -> List[Passage]:+ async def insert_archival_memory_async(+ self, agent_id: str, memory_contents: str, actor: User, tags: Optional[List[str]], created_at: Optional[datetime]+ ) -> List[Passage]:# Get the agent object (loaded in memory)agent_state = await self.agent_manager.get_agent_by_id_async(agent_id=agent_id, actor=actor)- # Insert passages into the archive+ # Use passage manager which handles dual-write to Turbopuffer if enabledpassages = await self.passage_manager.insert_passage(agent_state=agent_state, text=memory_contents, actor=actor)- return passages+ # TODO: Add support for tags and created_at parameters+ # Currently PassageManager.insert_passage doesn't support these parameters- def modify_archival_memory(self, agent_id: str, memory_id: str, passage: PassageUpdate, actor: User) -> List[Passage]:- passage = Passage(**passage.model_dump(exclude_unset=True, exclude_none=True))- passages = self.passage_manager.update_passage_by_id(passage_id=memory_id, passage=passage, actor=actor)return passagesasync def delete_archival_memory_async(self, memory_id: str, actor: User):@@ -1270,7 +1270,7 @@ class SyncServer(Server):await self.source_manager.delete_source(source_id=source_id, actor=actor)# delete data from passage store- passages_to_be_deleted = await self.agent_manager.list_passages_async(actor=actor, source_id=source_id, limit=None)+ passages_to_be_deleted = await self.agent_manager.query_source_passages_async(actor=actor, source_id=source_id, limit=None)await self.passage_manager.delete_source_passages_async(actor=actor, passages=passages_to_be_deleted)# TODO: delete data from agent passage stores (?)@@ -1316,27 +1316,6 @@ class SyncServer(Server):async def sleeptime_document_ingest_async(self, main_agent: AgentState, source: Source, actor: User, clear_history: bool = False) -> None:- # TEMPORARILY DISABLE UNTIL V2- # sleeptime_agent_state = await self.create_document_sleeptime_agent_async(main_agent, source, actor, clear_history)- # sleeptime_agent = LettaAgent(- # agent_id=sleeptime_agent_state.id,- # message_manager=self.message_manager,- # agent_manager=self.agent_manager,- # block_manager=self.block_manager,- # job_manager=self.job_manager,- # passage_manager=self.passage_manager,- # actor=actor,- # step_manager=self.step_manager,- # telemetry_manager=self.telemetry_manager if settings.llm_api_logging else NoopTelemetryManager(),- # )- # passages = await self.agent_manager.list_passages_async(actor=actor, source_id=source.id)- # for passage in passages:- # await sleeptime_agent.step(- # input_messages=[- # MessageCreate(role="user", content=passage.text),- # ]- # )- # await self.agent_manager.delete_agent_async(agent_id=sleeptime_agent_state.id, actor=actor)passasync def _remove_file_from_agent(self, agent_id: str, file_id: str, actor: User) -> None:diff --git a/letta/services/agent_manager.py b/letta/services/agent_manager.pyindex 46d25e16d..6a772b1f5 100644--- a/letta/services/agent_manager.py+++ b/letta/services/agent_manager.py@@ -48,7 +48,7 @@ from letta.schemas.block import DEFAULT_BLOCKSfrom letta.schemas.block import Block as PydanticBlockfrom letta.schemas.block import BlockUpdatefrom letta.schemas.embedding_config import EmbeddingConfig-from letta.schemas.enums import ProviderType, ToolType+from letta.schemas.enums import ProviderType, ToolType, VectorDBProviderfrom letta.schemas.file import FileMetadata as PydanticFileMetadatafrom letta.schemas.group import Group as PydanticGroupfrom letta.schemas.group import ManagerType@@ -67,6 +67,7 @@ from letta.serialize_schemas.marshmallow_message import SerializedMessageSchemafrom letta.serialize_schemas.marshmallow_tool import SerializedToolSchemafrom letta.serialize_schemas.pydantic_agent_schema import AgentSchemafrom letta.server.db import db_registry+from letta.services.archive_manager import ArchiveManagerfrom letta.services.block_manager import BlockManagerfrom letta.services.context_window_calculator.context_window_calculator import ContextWindowCalculatorfrom letta.services.context_window_calculator.token_counter import AnthropicTokenCounter, TiktokenCounter@@ -116,6 +117,7 @@ class AgentManager:self.passage_manager = PassageManager()self.identity_manager = IdentityManager()self.file_agent_manager = FileAgentManager()+ self.archive_manager = ArchiveManager()@staticmethoddef _should_exclude_model_from_base_tool_rules(model: str) -> bool:@@ -2520,7 +2522,20 @@ class AgentManager:embedding_config: Optional[EmbeddingConfig] = None,agent_only: bool = False,) -> List[PydanticPassage]:- """Lists all passages attached to an agent."""+ """+ DEPRECATED: Use query_source_passages_async or query_agent_passages_async instead.+ This method is kept only for test compatibility and will be removed in a future version.++ Lists all passages attached to an agent (combines both source and agent passages).+ """+ import warnings++ warnings.warn(+ "list_passages_async is deprecated. Use query_source_passages_async or query_agent_passages_async instead.",+ DeprecationWarning,+ stacklevel=2,+ )+async with db_registry.async_session() as session:main_query = await build_passage_query(actor=actor,@@ -2567,7 +2582,7 @@ class AgentManager:@enforce_types@trace_method- async def list_source_passages_async(+ async def query_source_passages_async(self,actor: PydanticUser,agent_id: Optional[str] = None,@@ -2615,7 +2630,7 @@ class AgentManager:@enforce_types@trace_method- async def list_agent_passages_async(+ async def query_agent_passages_async(self,actor: PydanticUser,agent_id: Optional[str] = None,@@ -2630,6 +2645,46 @@ class AgentManager:embedding_config: Optional[EmbeddingConfig] = None,) -> List[PydanticPassage]:"""Lists all passages attached to an agent."""+ # Check if we should use Turbopuffer for vector search+ if embed_query and agent_id and query_text and embedding_config:+ # Get archive IDs for the agent+ archive_ids = await self.get_agent_archive_ids_async(agent_id=agent_id, actor=actor)++ if archive_ids:+ # TODO: Remove this restriction once we support multiple archives with mixed vector DB providers+ if len(archive_ids) > 1:+ raise ValueError(f"Agent {agent_id} has multiple archives, which is not yet supported for vector search")++ # Get archive to check vector_db_provider+ archive = await self.archive_manager.get_archive_by_id_async(archive_id=archive_ids[0], actor=actor)++ # Use Turbopuffer for vector search if archive is configured for TPUF+ if archive.vector_db_provider == VectorDBProvider.TPUF:+ from letta.helpers.tpuf_client import TurbopufferClient+ from letta.llm_api.llm_client import LLMClient++ # Generate embedding for query+ embedding_client = LLMClient.create(+ provider_type=embedding_config.embedding_endpoint_type,+ actor=actor,+ )+ embeddings = await embedding_client.request_embeddings([query_text], embedding_config)+ query_embedding = embeddings[0]++ # Query Turbopuffer+ tpuf_client = TurbopufferClient()+ passages_with_scores = await tpuf_client.query_passages(+ archive_id=archive_ids[0],+ query_embedding=query_embedding,+ top_k=limit,+ )++ # Return just the passages (without scores)+ return [passage for passage, _ in passages_with_scores]+ else:+ return []++ # Fall back to SQL-based search for non-vector queries or NATIVE archivesasync with db_registry.async_session() as session:main_query = await build_agent_passage_query(actor=actor,diff --git a/letta/services/archive_manager.py b/letta/services/archive_manager.pyindex 86a9e5466..e547ac074 100644--- a/letta/services/archive_manager.py+++ b/letta/services/archive_manager.py@@ -2,11 +2,13 @@ from typing import List, Optionalfrom sqlalchemy import select+from letta.helpers.tpuf_client import should_use_tpuffrom letta.log import get_loggerfrom letta.orm import ArchivalPassagefrom letta.orm import Archive as ArchiveModelfrom letta.orm import ArchivesAgentsfrom letta.schemas.archive import Archive as PydanticArchive+from letta.schemas.enums import VectorDBProviderfrom letta.schemas.user import User as PydanticUserfrom letta.server.db import db_registryfrom letta.utils import enforce_types@@ -27,10 +29,14 @@ class ArchiveManager:"""Create a new archive."""try:with db_registry.session() as session:+ # determine vector db provider based on settings+ vector_db_provider = VectorDBProvider.TPUF if should_use_tpuf() else VectorDBProvider.NATIVE+archive = ArchiveModel(name=name,description=description,organization_id=actor.organization_id,+ vector_db_provider=vector_db_provider,)archive.create(session, actor=actor)return archive.to_pydantic()@@ -48,10 +54,14 @@ class ArchiveManager:"""Create a new archive."""try:async with db_registry.async_session() as session:+ # determine vector db provider based on settings+ vector_db_provider = VectorDBProvider.TPUF if should_use_tpuf() else VectorDBProvider.NATIVE+archive = ArchiveModel(name=name,description=description,organization_id=actor.organization_id,+ vector_db_provider=vector_db_provider,)await archive.create_async(session, actor=actor)return archive.to_pydantic()diff --git a/letta/services/passage_manager.py b/letta/services/passage_manager.pyindex 39cd07ce1..7a9e825e2 100644--- a/letta/services/passage_manager.py+++ b/letta/services/passage_manager.py@@ -14,6 +14,7 @@ from letta.orm.errors import NoResultFoundfrom letta.orm.passage import ArchivalPassage, SourcePassagefrom letta.otel.tracing import trace_methodfrom letta.schemas.agent import AgentState+from letta.schemas.enums import VectorDBProviderfrom letta.schemas.file import FileMetadata as PydanticFileMetadatafrom letta.schemas.passage import Passage as PydanticPassagefrom letta.schemas.user import User as PydanticUser@@ -489,6 +490,8 @@ class PassageManager:embeddings = await embedding_client.request_embeddings(text_chunks, agent_state.embedding_config)passages = []++ # Always write to SQL database firstfor chunk_text, embedding in zip(text_chunks, embeddings):passage = await self.create_agent_passage_async(PydanticPassage(@@ -502,6 +505,26 @@ class PassageManager:)passages.append(passage)+ # If archive uses Turbopuffer, also write to Turbopuffer (dual-write)+ if archive.vector_db_provider == VectorDBProvider.TPUF:+ from letta.helpers.tpuf_client import TurbopufferClient++ tpuf_client = TurbopufferClient()++ # Extract IDs and texts from the created passages+ passage_ids = [p.id for p in passages]+ passage_texts = [p.text for p in passages]++ # Insert to Turbopuffer with the same IDs as SQL+ await tpuf_client.insert_archival_memories(+ archive_id=archive.id,+ text_chunks=passage_texts,+ embeddings=embeddings,+ passage_ids=passage_ids, # Use same IDs as SQL+ organization_id=actor.organization_id,+ created_at=passages[0].created_at if passages else None,+ )+return passagesexcept Exception as e:@@ -655,7 +678,20 @@ class PassageManager:async with db_registry.async_session() as session:try:passage = await ArchivalPassage.read_async(db_session=session, identifier=passage_id, actor=actor)+ archive_id = passage.archive_id++ # Delete from SQL firstawait passage.hard_delete_async(session, actor=actor)++ # Check if archive uses Turbopuffer and dual-delete+ if archive_id:+ archive = await self.archive_manager.get_archive_by_id_async(archive_id=archive_id, actor=actor)+ if archive.vector_db_provider == VectorDBProvider.TPUF:+ from letta.helpers.tpuf_client import TurbopufferClient++ tpuf_client = TurbopufferClient()+ await tpuf_client.delete_passage(archive_id=archive_id, passage_id=passage_id)+return Trueexcept NoResultFound:raise NoResultFound(f"Agent passage with id {passage_id} not found.")@@ -812,12 +848,34 @@ class PassageManager:@trace_methodasync def delete_agent_passages_async(self,- actor: PydanticUser,passages: List[PydanticPassage],+ actor: PydanticUser,) -> bool:"""Delete multiple agent passages."""+ if not passages:+ return True+async with db_registry.async_session() as session:+ # Delete from SQL firstawait ArchivalPassage.bulk_hard_delete_async(db_session=session, identifiers=[p.id for p in passages], actor=actor)++ # Group passages by archive_id for efficient Turbopuffer deletion+ passages_by_archive = {}+ for passage in passages:+ if passage.archive_id:+ if passage.archive_id not in passages_by_archive:+ passages_by_archive[passage.archive_id] = []+ passages_by_archive[passage.archive_id].append(passage.id)++ # Check each archive and delete from Turbopuffer if needed+ for archive_id, passage_ids in passages_by_archive.items():+ archive = await self.archive_manager.get_archive_by_id_async(archive_id=archive_id, actor=actor)+ if archive.vector_db_provider == VectorDBProvider.TPUF:+ from letta.helpers.tpuf_client import TurbopufferClient++ tpuf_client = TurbopufferClient()+ await tpuf_client.delete_passages(archive_id=archive_id, passage_ids=passage_ids)+return True@enforce_typesdiff --git a/letta/services/tool_executor/core_tool_executor.py b/letta/services/tool_executor/core_tool_executor.pyindex 35da4c28e..1bd01a6a3 100644--- a/letta/services/tool_executor/core_tool_executor.py+++ b/letta/services/tool_executor/core_tool_executor.py@@ -143,7 +143,7 @@ class LettaCoreToolExecutor(ToolExecutor):try:# Get results using passage manager- all_results = await AgentManager().list_agent_passages_async(+ all_results = await AgentManager().query_agent_passages_async(actor=actor,agent_id=agent_state.id,query_text=query,diff --git a/letta/services/tool_executor/files_tool_executor.py b/letta/services/tool_executor/files_tool_executor.pyindex 047a7072c..c3daa9c4d 100644--- a/letta/services/tool_executor/files_tool_executor.py+++ b/letta/services/tool_executor/files_tool_executor.py@@ -661,7 +661,7 @@ class LettaFileToolExecutor(ToolExecutor):async def _search_files_traditional(self, agent_state: AgentState, query: str, limit: int) -> str:"""Traditional search using existing passage manager."""# Get semantic search results- passages = await self.agent_manager.list_source_passages_async(+ passages = await self.agent_manager.query_source_passages_async(actor=self.actor,agent_id=agent_state.id,query_text=query,diff --git a/letta/settings.py b/letta/settings.pyindex 87a875347..6f9c35318 100644--- a/letta/settings.py+++ b/letta/settings.py@@ -300,7 +300,7 @@ class Settings(BaseSettings):# For tpuf - currently only for archival memoriesuse_tpuf: bool = Falsetpuf_api_key: Optional[str] = None- tpuf_region: str = "gcp-us-central1.turbopuffer.com"+ tpuf_region: str = "gcp-us-central1"# File processing timeout settingsfile_processing_timeout_minutes: int = 30diff --git a/tests/conftest.py b/tests/conftest.pyindex 751ec8064..c88175a05 100644--- a/tests/conftest.py+++ b/tests/conftest.py@@ -104,6 +104,62 @@ def disable_pinecone() -> Generator[None, None, None]:settings.pinecone_api_key = original_pinecone_api_key+def disable_turbopuffer() -> Generator[None, None, None]:+ """+ Temporarily disables Turbopuffer by setting `settings.use_tpuf` to False+ and `settings.tpuf_api_key` to None for the duration of the test.+ Also sets environment to DEV for testing.+ Restores the original values afterward.+ """+ from letta.settings import settings++ original_use_tpuf = settings.use_tpuf+ original_tpuf_api_key = settings.tpuf_api_key+ original_environment = settings.environment+ settings.use_tpuf = False+ settings.tpuf_api_key = None+ settings.environment = "DEV"+ yield+ settings.use_tpuf = original_use_tpuf+ settings.tpuf_api_key = original_tpuf_api_key+ settings.environment = original_environment+++def turbopuffer_mode(request) -> Generator[None, None, None]:+ """+ Parametrizable fixture to enable/disable Turbopuffer mode.++ Usage:+ @pytest.mark.parametrize("turbopuffer_mode", [True, False], indirect=True)+ def test_function(turbopuffer_mode, ...):+ # Test runs twice - once with Turbopuffer enabled, once disabled+ """+ from letta.settings import settings++ enable_tpuf = request.param+ original_use_tpuf = settings.use_tpuf+ original_tpuf_api_key = settings.tpuf_api_key+ original_environment = settings.environment++ # Set environment to DEV for testing+ settings.environment = "DEV"++ if not enable_tpuf:+ # Disable Turbopuffer by setting use_tpuf to False+ settings.use_tpuf = False+ settings.tpuf_api_key = None+ # If enable_tpuf is True, leave the original settings unchanged++ yield++ # Restore original settings+ settings.use_tpuf = original_use_tpuf+ settings.tpuf_api_key = original_tpuf_api_key+ settings.environment = original_environment++@pytest.fixturedef check_e2b_key_is_set():from letta.settings import tool_settingsdiff --git a/tests/test_managers.py b/tests/test_managers.pyindex fd2f32f04..5a15f6e47 100644--- a/tests/test_managers.py+++ b/tests/test_managers.py@@ -2670,21 +2670,18 @@ async def test_refresh_memory_async(server: SyncServer, default_user):@pytest.mark.asyncio-async def test_agent_list_passages_basic(server, default_user, sarah_agent, agent_passages_setup):+async def test_agent_list_passages_basic(server, default_user, sarah_agent, agent_passages_setup, disable_turbopuffer):"""Test basic listing functionality of agent passages"""all_passages = await server.agent_manager.list_passages_async(actor=default_user, agent_id=sarah_agent.id)assert len(all_passages) == 5 # 3 source + 2 agent passages- source_passages = await server.agent_manager.list_source_passages_async(actor=default_user, agent_id=sarah_agent.id)+ source_passages = await server.agent_manager.query_source_passages_async(actor=default_user, agent_id=sarah_agent.id)assert len(source_passages) == 3 # 3 source + 2 agent passages- agent_passages = await server.agent_manager.list_agent_passages_async(actor=default_user, agent_id=sarah_agent.id)- assert len(agent_passages) == 2 # 3 source + 2 agent passages-@pytest.mark.asyncio-async def test_agent_list_passages_ordering(server, default_user, sarah_agent, agent_passages_setup):+async def test_agent_list_passages_ordering(server, default_user, sarah_agent, agent_passages_setup, disable_turbopuffer):"""Test ordering of agent passages"""# Test ascending order@@ -2701,7 +2698,7 @@ async def test_agent_list_passages_ordering(server, default_user, sarah_agent, a@pytest.mark.asyncio-async def test_agent_list_passages_pagination(server, default_user, sarah_agent, agent_passages_setup):+async def test_agent_list_passages_pagination(server, default_user, sarah_agent, agent_passages_setup, disable_turbopuffer):"""Test pagination of agent passages"""# Test limit@@ -2742,7 +2739,7 @@ async def test_agent_list_passages_pagination(server, default_user, sarah_agent,@pytest.mark.asyncio-async def test_agent_list_passages_text_search(server, default_user, sarah_agent, agent_passages_setup):+async def test_agent_list_passages_text_search(server, default_user, sarah_agent, agent_passages_setup, disable_turbopuffer):"""Test text search functionality of agent passages"""# Test text search for source passages@@ -2759,7 +2756,7 @@ async def test_agent_list_passages_text_search(server, default_user, sarah_agent@pytest.mark.asyncio-async def test_agent_list_passages_agent_only(server, default_user, sarah_agent, agent_passages_setup):+async def test_agent_list_passages_agent_only(server, default_user, sarah_agent, agent_passages_setup, disable_turbopuffer):"""Test text search functionality of agent passages"""# Test text search for agent passages@@ -2768,7 +2765,7 @@ async def test_agent_list_passages_agent_only(server, default_user, sarah_agent,@pytest.mark.asyncio-async def test_agent_list_passages_filtering(server, default_user, sarah_agent, default_source, agent_passages_setup):+async def test_agent_list_passages_filtering(server, default_user, sarah_agent, default_source, agent_passages_setup, disable_turbopuffer):"""Test filtering functionality of agent passages"""# Test source filtering@@ -2804,7 +2801,9 @@ def mock_embed_model(mock_embeddings):return mock_model-async def test_agent_list_passages_vector_search(server, default_user, sarah_agent, default_source, default_file, mock_embed_model):+async def test_agent_list_passages_vector_search(+ server, default_user, sarah_agent, default_source, default_file, mock_embed_model, disable_turbopuffer+):"""Test vector search functionality of agent passages"""embed_model = mock_embed_modeldiff --git a/tests/test_turbopuffer_integration.py b/tests/test_turbopuffer_integration.pynew file mode 100644index 000000000..201bae6fc--- /dev/null+++ b/tests/test_turbopuffer_integration.py@@ -0,0 +1,330 @@+import uuid+from datetime import datetime, timezone++import pytest++from letta.config import LettaConfig+from letta.helpers.tpuf_client import TurbopufferClient, should_use_tpuf+from letta.schemas.embedding_config import EmbeddingConfig+from letta.schemas.enums import VectorDBProvider+from letta.server.server import SyncServer+from letta.settings import settings++[email protected](scope="module")+def server():+ """Server fixture for testing"""+ config = LettaConfig.load()+ config.save()+ server = SyncServer(init_with_default_org_and_user=False)+ return server+++async def sarah_agent(server, default_user):+ """Create a test agent named Sarah"""+ from letta.schemas.agent import CreateAgent+ from letta.schemas.embedding_config import EmbeddingConfig+ from letta.schemas.llm_config import LLMConfig++ agent = await server.agent_manager.create_agent_async(+ agent_create=CreateAgent(+ name="Sarah",+ memory_blocks=[],+ llm_config=LLMConfig.default_config("gpt-4o-mini"),+ embedding_config=EmbeddingConfig.default_config(provider="openai"),+ include_base_tools=False,+ ),+ actor=default_user,+ )+ yield agent+ # Cleanup+ try:+ await server.agent_manager.delete_agent_async(agent.id, default_user)+ except:+ pass+++def enable_turbopuffer():+ """Temporarily enable Turbopuffer for testing with a test API key"""+ original_use_tpuf = settings.use_tpuf+ original_api_key = settings.tpuf_api_key+ original_environment = settings.environment++ # Enable Turbopuffer with test key+ settings.use_tpuf = True+ # Use the existing tpuf_api_key if set, otherwise keep original+ if not settings.tpuf_api_key:+ settings.tpuf_api_key = original_api_key+ # Set environment to DEV for testing+ settings.environment = "DEV"++ yield++ # Restore original values+ settings.use_tpuf = original_use_tpuf+ settings.tpuf_api_key = original_api_key+ settings.environment = original_environment+++class TestTurbopufferIntegration:+ """Test Turbopuffer integration functionality with real connections"""++ def test_should_use_tpuf_with_settings(self):+ """Test that should_use_tpuf correctly reads settings"""+ # Save original values+ original_use_tpuf = settings.use_tpuf+ original_api_key = settings.tpuf_api_key++ try:+ # Test when both are set+ settings.use_tpuf = True+ settings.tpuf_api_key = "test-key"+ assert should_use_tpuf() is True++ # Test when use_tpuf is False+ settings.use_tpuf = False+ assert should_use_tpuf() is False++ # Test when API key is missing+ settings.use_tpuf = True+ settings.tpuf_api_key = None+ assert should_use_tpuf() is False+ finally:+ # Restore original values+ settings.use_tpuf = original_use_tpuf+ settings.tpuf_api_key = original_api_key++ @pytest.mark.asyncio+ async def test_archive_creation_with_tpuf_enabled(self, server, default_user, enable_turbopuffer):+ """Test that archives are created with correct vector_db_provider when TPUF is enabled"""+ archive = await server.archive_manager.create_archive_async(name="Test Archive with TPUF", actor=default_user)+ assert archive.vector_db_provider == VectorDBProvider.TPUF+ # TODO: Add cleanup when delete_archive method is available++ @pytest.mark.asyncio+ async def test_archive_creation_with_tpuf_disabled(self, server, default_user, disable_turbopuffer):+ """Test that archives default to NATIVE when TPUF is disabled"""+ archive = await server.archive_manager.create_archive_async(name="Test Archive without TPUF", actor=default_user)+ assert archive.vector_db_provider == VectorDBProvider.NATIVE+ # TODO: Add cleanup when delete_archive method is available++ @pytest.mark.asyncio+ @pytest.mark.skipif(not settings.tpuf_api_key, reason="Turbopuffer API key not configured for testing")+ async def test_dual_write_and_query_with_real_tpuf(self, server, default_user, sarah_agent, enable_turbopuffer):+ """Test that passages are written to both SQL and Turbopuffer with real connection and can be queried"""++ # Create a TPUF-enabled archive+ archive = await server.archive_manager.create_archive_async(name="Test TPUF Archive for Real Dual Write", actor=default_user)+ assert archive.vector_db_provider == VectorDBProvider.TPUF++ # Attach the agent to the archive+ await server.archive_manager.attach_agent_to_archive_async(+ agent_id=sarah_agent.id, archive_id=archive.id, is_owner=True, actor=default_user+ )++ try:+ # Insert passages - this should trigger dual write+ test_passages = [+ "Turbopuffer is a vector database optimized for performance.",+ "This integration test verifies dual-write functionality.",+ "Metadata attributes should be properly stored in Turbopuffer.",+ ]++ for text in test_passages:+ passages = await server.passage_manager.insert_passage(agent_state=sarah_agent, text=text, actor=default_user)+ assert passages is not None+ assert len(passages) > 0++ # Verify passages are in SQL - use agent_manager to list passages+ sql_passages = await server.agent_manager.query_agent_passages_async(actor=default_user, agent_id=sarah_agent.id, limit=10)+ assert len(sql_passages) >= len(test_passages)+ for text in test_passages:+ assert any(p.text == text for p in sql_passages)++ # Test vector search which should use Turbopuffer+ embedding_config = sarah_agent.embedding_config or EmbeddingConfig.default_config(provider="openai")++ # Perform vector search+ vector_results = await server.agent_manager.query_agent_passages_async(+ actor=default_user,+ agent_id=sarah_agent.id,+ query_text="turbopuffer vector database",+ embedding_config=embedding_config,+ embed_query=True,+ limit=5,+ )++ # Should find relevant passages via Turbopuffer vector search+ assert len(vector_results) > 0+ # The most relevant result should be about Turbopuffer+ assert any("Turbopuffer" in p.text or "vector" in p.text for p in vector_results)++ # Test deletion - should delete from both+ passage_to_delete = sql_passages[0]+ await server.passage_manager.delete_agent_passages_async([passage_to_delete], default_user)++ # Verify deleted from SQL+ remaining = await server.agent_manager.query_agent_passages_async(actor=default_user, agent_id=sarah_agent.id, limit=10)+ assert not any(p.id == passage_to_delete.id for p in remaining)++ # Verify vector search no longer returns deleted passage+ vector_results_after_delete = await server.agent_manager.query_agent_passages_async(+ actor=default_user,+ agent_id=sarah_agent.id,+ query_text=passage_to_delete.text,+ embedding_config=embedding_config,+ embed_query=True,+ limit=10,+ )+ assert not any(p.id == passage_to_delete.id for p in vector_results_after_delete)++ finally:+ # TODO: Clean up archive when delete_archive method is available+ pass++ @pytest.mark.asyncio+ async def test_turbopuffer_metadata_attributes(self, enable_turbopuffer):+ """Test that Turbopuffer properly stores and retrieves metadata attributes"""++ # Only run if we have a real API key+ if not settings.tpuf_api_key:+ pytest.skip("No Turbopuffer API key available")++ client = TurbopufferClient()+ archive_id = f"test-archive-{datetime.now().timestamp()}"++ try:+ # Insert passages with various metadata+ test_data = [+ {+ "id": f"passage-{uuid.uuid4()}",+ "text": "First test passage",+ "vector": [0.1] * 1536,+ "organization_id": "org-123",+ "created_at": datetime.now(timezone.utc),+ },+ {+ "id": f"passage-{uuid.uuid4()}",+ "text": "Second test passage",+ "vector": [0.2] * 1536,+ "organization_id": "org-123",+ "created_at": datetime.now(timezone.utc),+ },+ {+ "id": f"passage-{uuid.uuid4()}",+ "text": "Third test passage from different org",+ "vector": [0.3] * 1536,+ "organization_id": "org-456",+ "created_at": datetime.now(timezone.utc),+ },+ ]++ # Insert all passages+ result = await client.insert_archival_memories(+ archive_id=archive_id,+ text_chunks=[d["text"] for d in test_data],+ embeddings=[d["vector"] for d in test_data],+ passage_ids=[d["id"] for d in test_data],+ organization_id="org-123", # Default org+ created_at=datetime.now(timezone.utc),+ )++ assert len(result) == 3++ # Query with organization filter+ query_vector = [0.15] * 1536+ results = await client.query_passages(+ archive_id=archive_id, query_embedding=query_vector, top_k=10, filters={"organization_id": "org-123"}+ )++ # Should only get passages from org-123+ assert len(results) >= 2 # At least the first two passages+ for passage, score in results:+ assert passage.organization_id == "org-123"++ # Clean up+ await client.delete_passages(archive_id=archive_id, passage_ids=[d["id"] for d in test_data])++ except Exception as e:+ # Clean up on error+ try:+ await client.delete_all_passages(archive_id)+ except:+ pass+ raise e++ @pytest.mark.asyncio+ async def test_native_only_operations(self, server, default_user, sarah_agent, disable_turbopuffer):+ """Test that operations work correctly when using only native PostgreSQL"""++ # Create archive (should be NATIVE since turbopuffer is disabled)+ archive = await server.archive_manager.get_or_create_default_archive_for_agent_async(+ agent_id=sarah_agent.id, agent_name=sarah_agent.name, actor=default_user+ )+ assert archive.vector_db_provider == VectorDBProvider.NATIVE++ # Insert passages - should only write to SQL+ text_content = "This is a test passage for native PostgreSQL only."+ passages = await server.passage_manager.insert_passage(agent_state=sarah_agent, text=text_content, actor=default_user)++ assert passages is not None+ assert len(passages) > 0++ # List passages - should work from SQL+ sql_passages = await server.agent_manager.query_agent_passages_async(actor=default_user, agent_id=sarah_agent.id, limit=10)+ assert any(p.text == text_content for p in sql_passages)++ # Vector search should use PostgreSQL pgvector+ embedding_config = sarah_agent.embedding_config or EmbeddingConfig.default_config(provider="openai")+ vector_results = await server.agent_manager.query_agent_passages_async(+ actor=default_user,+ agent_id=sarah_agent.id,+ query_text="native postgresql",+ embedding_config=embedding_config,+ embed_query=True,+ )++ # Should still work with native PostgreSQL+ assert isinstance(vector_results, list)++[email protected]("turbopuffer_mode", [True, False], indirect=True)+class TestTurbopufferParametrized:+ """Test that functionality works with and without Turbopuffer enabled"""++ @pytest.mark.asyncio+ async def test_passage_operations_with_mode(self, turbopuffer_mode, server, default_user, sarah_agent):+ """Test that passage operations work in both modes"""++ # Get or create archive+ archive = await server.archive_manager.get_or_create_default_archive_for_agent_async(+ agent_id=sarah_agent.id, agent_name=sarah_agent.name, actor=default_user+ )++ # Check that vector_db_provider matches the mode+ if settings.use_tpuf and settings.tpuf_api_key:+ expected_provider = VectorDBProvider.TPUF+ else:+ expected_provider = VectorDBProvider.NATIVE+ assert archive.vector_db_provider == expected_provider++ # Test inserting a passage (should work in both modes)+ test_text = f"Test passage for {expected_provider} mode"+ passages = await server.passage_manager.insert_passage(agent_state=sarah_agent, text=test_text, actor=default_user)++ assert passages is not None+ assert len(passages) > 0+ assert passages[0].text == test_text++ # List passages should work in both modes+ listed = await server.agent_manager.query_agent_passages_async(actor=default_user, agent_id=sarah_agent.id, limit=10)+ assert any(p.text == test_text for p in listed)++ # Delete should work in both modes+ await server.passage_manager.delete_agent_passages_async(passages, default_user)++ # Verify deletion+ remaining = await server.agent_manager.query_agent_passages_async(actor=default_user, agent_id=sarah_agent.id, limit=10)+ assert not any(p.id == passages[0].id for p in remaining)