Platform for stateful agents: AI with advanced memory that can learn and self-improve over time.
feat: add tool embedding and search [LET-6333] (#6398)
Ari Webb3e02f12dfdfc
diff --git a/fern/openapi.json b/fern/openapi.jsonindex f00151833..781c3f9ed 100644--- a/fern/openapi.json+++ b/fern/openapi.json@@ -1275,6 +1275,51 @@}}},+ "/v1/tools/search": {+ "post": {+ "tags": ["tools"],+ "summary": "Search Tools",+ "description": "Search tools using semantic search.\n\nRequires tool embedding to be enabled (embed_tools=True). Uses vector search,\nfull-text search, or hybrid mode to find tools matching the query.\n\nReturns tools ranked by relevance with their search scores.",+ "operationId": "search_tools",+ "parameters": [],+ "requestBody": {+ "required": true,+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/ToolSearchRequest"+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "Successful Response",+ "content": {+ "application/json": {+ "schema": {+ "type": "array",+ "items": {+ "$ref": "#/components/schemas/ToolSearchResult"+ },+ "title": "Response Search Tools"+ }+ }+ }+ },+ "422": {+ "description": "Validation Error",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/HTTPValidationError"+ }+ }+ }+ }+ }+ }+ },"/v1/tools/add-base-tools": {"post": {"tags": ["tools"],@@ -36392,6 +36437,125 @@"required": ["source_code", "args"],"title": "ToolRunFromSource"},+ "ToolSearchRequest": {+ "properties": {+ "query": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "title": "Query",+ "description": "Text query for semantic search."+ },+ "search_mode": {+ "type": "string",+ "enum": ["vector", "fts", "hybrid"],+ "title": "Search Mode",+ "description": "Search mode: vector, fts, or hybrid.",+ "default": "hybrid"+ },+ "tool_types": {+ "anyOf": [+ {+ "items": {+ "type": "string"+ },+ "type": "array"+ },+ {+ "type": "null"+ }+ ],+ "title": "Tool Types",+ "description": "Filter by tool types (e.g., 'custom', 'letta_core')."+ },+ "tags": {+ "anyOf": [+ {+ "items": {+ "type": "string"+ },+ "type": "array"+ },+ {+ "type": "null"+ }+ ],+ "title": "Tags",+ "description": "Filter by tags (match any)."+ },+ "limit": {+ "type": "integer",+ "maximum": 100,+ "minimum": 1,+ "title": "Limit",+ "description": "Maximum number of results to return.",+ "default": 50+ }+ },+ "additionalProperties": false,+ "type": "object",+ "title": "ToolSearchRequest",+ "description": "Request model for searching tools using semantic search."+ },+ "ToolSearchResult": {+ "properties": {+ "tool": {+ "$ref": "#/components/schemas/Tool",+ "description": "The matched tool."+ },+ "embedded_text": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "title": "Embedded Text",+ "description": "The embedded text content used for matching."+ },+ "fts_rank": {+ "anyOf": [+ {+ "type": "integer"+ },+ {+ "type": "null"+ }+ ],+ "title": "Fts Rank",+ "description": "Full-text search rank position."+ },+ "vector_rank": {+ "anyOf": [+ {+ "type": "integer"+ },+ {+ "type": "null"+ }+ ],+ "title": "Vector Rank",+ "description": "Vector search rank position."+ },+ "combined_score": {+ "type": "number",+ "title": "Combined Score",+ "description": "Combined relevance score (RRF for hybrid mode)."+ }+ },+ "additionalProperties": false,+ "type": "object",+ "required": ["tool", "combined_score"],+ "title": "ToolSearchResult",+ "description": "Result from a tool search operation."+ },"ToolType": {"type": "string","enum": [diff --git a/letta/helpers/tpuf_client.py b/letta/helpers/tpuf_client.pyindex 52c4c62de..38107060a 100644--- a/letta/helpers/tpuf_client.py+++ b/letta/helpers/tpuf_client.py@@ -1,6 +1,7 @@"""Turbopuffer utilities for archival memory storage."""import asyncio+import jsonimport loggingfrom datetime import datetime, timezonefrom typing import Any, Callable, List, Optional, Tuple@@ -29,6 +30,11 @@ def should_use_tpuf_for_messages() -> bool:return should_use_tpuf() and bool(settings.embed_all_messages)+def should_use_tpuf_for_tools() -> bool:+ """Check if Turbopuffer should be used for tools."""+ return should_use_tpuf() and bool(settings.embed_tools)++class TurbopufferClient:"""Client for managing archival memory with Turbopuffer vector database."""@@ -104,6 +110,157 @@ class TurbopufferClient:return namespace_name+ @trace_method+ async def _get_tool_namespace_name(self, organization_id: str) -> str:+ """Get namespace name for tools (org-scoped).++ Args:+ organization_id: Organization ID for namespace generation++ Returns:+ The org-scoped namespace name for tools+ """+ environment = settings.environment+ if environment:+ namespace_name = f"tools_{organization_id}_{environment.lower()}"+ else:+ namespace_name = f"tools_{organization_id}"++ return namespace_name++ def _extract_tool_text(self, tool: "PydanticTool") -> str:+ """Extract searchable text from a tool for embedding.++ Combines name, description, and JSON schema into a structured format+ that provides rich context for semantic search.++ Args:+ tool: The tool to extract text from++ Returns:+ JSON-formatted string containing tool information+ """++ parts = {+ "name": tool.name or "",+ "description": tool.description or "",+ }++ # Extract parameter information from JSON schema+ if tool.json_schema:+ # Include function description from schema if different from tool description+ schema_description = tool.json_schema.get("description", "")+ if schema_description and schema_description != tool.description:+ parts["schema_description"] = schema_description++ # Extract parameter information+ parameters = tool.json_schema.get("parameters", {})+ if parameters:+ properties = parameters.get("properties", {})+ param_descriptions = []+ for param_name, param_info in properties.items():+ param_desc = param_info.get("description", "")+ param_type = param_info.get("type", "any")+ if param_desc:+ param_descriptions.append(f"{param_name} ({param_type}): {param_desc}")+ else:+ param_descriptions.append(f"{param_name} ({param_type})")+ if param_descriptions:+ parts["parameters"] = param_descriptions++ # Include tags for additional context+ if tool.tags:+ parts["tags"] = tool.tags++ return json.dumps(parts)++ @trace_method+ async def insert_tools(+ self,+ tools: List["PydanticTool"],+ organization_id: str,+ actor: "PydanticUser",+ ) -> bool:+ """Insert tools into Turbopuffer.++ Args:+ tools: List of tools to store+ organization_id: Organization ID for the tools+ actor: User actor for embedding generation++ Returns:+ True if successful+ """+ from turbopuffer import AsyncTurbopuffer++ if not tools:+ return True++ # Extract text and filter out empty content+ tool_texts = []+ valid_tools = []+ for tool in tools:+ text = self._extract_tool_text(tool)+ if text.strip():+ tool_texts.append(text)+ valid_tools.append(tool)++ if not valid_tools:+ logger.warning("All tools had empty text content, skipping insertion")+ return True++ # Generate embeddings+ embeddings = await self._generate_embeddings(tool_texts, actor)++ namespace_name = await self._get_tool_namespace_name(organization_id)++ # Prepare column-based data+ ids = []+ vectors = []+ texts = []+ names = []+ organization_ids = []+ tool_types = []+ tags_arrays = []+ created_ats = []++ for tool, text, embedding in zip(valid_tools, tool_texts, embeddings):+ ids.append(tool.id)+ vectors.append(embedding)+ texts.append(text)+ names.append(tool.name or "")+ organization_ids.append(organization_id)+ tool_types.append(tool.tool_type.value if tool.tool_type else "custom")+ tags_arrays.append(tool.tags or [])+ created_ats.append(getattr(tool, "created_at", None) or datetime.now(timezone.utc))++ upsert_columns = {+ "id": ids,+ "vector": vectors,+ "text": texts,+ "name": names,+ "organization_id": organization_ids,+ "tool_type": tool_types,+ "tags": tags_arrays,+ "created_at": created_ats,+ }++ try:+ async with _GLOBAL_TURBOPUFFER_SEMAPHORE:+ async with AsyncTurbopuffer(api_key=self.api_key, region=self.region) as client:+ namespace = client.namespace(namespace_name)+ await namespace.write(+ upsert_columns=upsert_columns,+ distance_metric="cosine_distance",+ schema={"text": {"type": "string", "full_text_search": True}},+ )+ logger.info(f"Successfully inserted {len(ids)} tools to Turbopuffer")+ return True++ except Exception as e:+ logger.error(f"Failed to insert tools to Turbopuffer: {e}")+ raise+@trace_methodasync def insert_archival_memories(self,@@ -1468,3 +1625,150 @@ class TurbopufferClient:except Exception as e:logger.error(f"Failed to delete source passages from Turbopuffer: {e}")raise++ # tool methods++ @trace_method+ async def delete_tools(self, organization_id: str, tool_ids: List[str]) -> bool:+ """Delete tools from Turbopuffer.++ Args:+ organization_id: Organization ID for namespace lookup+ tool_ids: List of tool IDs to delete++ Returns:+ True if successful+ """+ from turbopuffer import AsyncTurbopuffer++ if not tool_ids:+ return True++ namespace_name = await self._get_tool_namespace_name(organization_id)++ try:+ async with AsyncTurbopuffer(api_key=self.api_key, region=self.region) as client:+ namespace = client.namespace(namespace_name)+ await namespace.write(deletes=tool_ids)+ logger.info(f"Successfully deleted {len(tool_ids)} tools from Turbopuffer")+ return True+ except Exception as e:+ logger.error(f"Failed to delete tools from Turbopuffer: {e}")+ raise++ @trace_method+ async def query_tools(+ self,+ organization_id: str,+ actor: "PydanticUser",+ query_text: Optional[str] = None,+ search_mode: str = "hybrid", # "vector", "fts", "hybrid", "timestamp"+ top_k: int = 50,+ tool_types: Optional[List[str]] = None,+ tags: Optional[List[str]] = None,+ vector_weight: float = 0.5,+ fts_weight: float = 0.5,+ ) -> List[Tuple[dict, float, dict]]:+ """Query tools from Turbopuffer using semantic search.++ Args:+ organization_id: Organization ID for namespace lookup+ actor: User actor for embedding generation+ query_text: Text query for search+ search_mode: Search mode - "vector", "fts", "hybrid", or "timestamp"+ top_k: Number of results to return+ tool_types: Optional list of tool types to filter by+ tags: Optional list of tags to filter by (match any)+ vector_weight: Weight for vector search in hybrid mode+ fts_weight: Weight for FTS in hybrid mode++ Returns:+ List of (tool_dict, score, metadata) tuples+ """+ # Generate embedding for vector/hybrid search+ query_embedding = None+ if query_text and search_mode in ["vector", "hybrid"]:+ embeddings = await self._generate_embeddings([query_text], actor)+ query_embedding = embeddings[0] if embeddings else None++ # Fallback to timestamp-based retrieval when no query+ if query_embedding is None and query_text is None and search_mode not in ["timestamp"]:+ search_mode = "timestamp"++ namespace_name = await self._get_tool_namespace_name(organization_id)++ # Build filters+ all_filters = []++ if tool_types:+ if len(tool_types) == 1:+ all_filters.append(("tool_type", "Eq", tool_types[0]))+ else:+ all_filters.append(("tool_type", "In", tool_types))++ if tags:+ all_filters.append(("tags", "ContainsAny", tags))++ # Combine filters+ final_filter = None+ if len(all_filters) == 1:+ final_filter = all_filters[0]+ elif len(all_filters) > 1:+ final_filter = ("And", all_filters)++ try:+ result = await self._execute_query(+ namespace_name=namespace_name,+ search_mode=search_mode,+ query_embedding=query_embedding,+ query_text=query_text,+ top_k=top_k,+ include_attributes=["text", "name", "organization_id", "tool_type", "tags", "created_at"],+ filters=final_filter,+ vector_weight=vector_weight,+ fts_weight=fts_weight,+ )++ if search_mode == "hybrid":+ vector_results = self._process_tool_query_results(result.results[0])+ fts_results = self._process_tool_query_results(result.results[1])+ results_with_metadata = self._reciprocal_rank_fusion(+ vector_results=vector_results,+ fts_results=fts_results,+ get_id_func=lambda d: d["id"],+ vector_weight=vector_weight,+ fts_weight=fts_weight,+ top_k=top_k,+ )+ return results_with_metadata+ else:+ results = self._process_tool_query_results(result)+ results_with_metadata = []+ for idx, tool_dict in enumerate(results):+ metadata = {+ "combined_score": 1.0 / (idx + 1),+ "search_mode": search_mode,+ f"{search_mode}_rank": idx + 1,+ }+ results_with_metadata.append((tool_dict, metadata["combined_score"], metadata))+ return results_with_metadata++ except Exception as e:+ logger.error(f"Failed to query tools from Turbopuffer: {e}")+ raise++ def _process_tool_query_results(self, result) -> List[dict]:+ """Process results from a tool query into tool dicts."""+ tools = []+ for row in result.rows:+ tool_dict = {+ "id": row.id,+ "text": getattr(row, "text", ""),+ "name": getattr(row, "name", ""),+ "organization_id": getattr(row, "organization_id", None),+ "tool_type": getattr(row, "tool_type", None),+ "tags": getattr(row, "tags", []),+ "created_at": getattr(row, "created_at", None),+ }+ tools.append(tool_dict)+ return toolsdiff --git a/letta/schemas/tool.py b/letta/schemas/tool.pyindex baab6f5f9..f1d950f7b 100644--- a/letta/schemas/tool.py+++ b/letta/schemas/tool.py@@ -1,4 +1,4 @@-from typing import Any, Dict, List, Optional+from typing import Any, Dict, List, Literal, Optionalfrom pydantic import ConfigDict, Field, model_validator@@ -206,3 +206,23 @@ class ToolRunFromSource(LettaBase):)pip_requirements: list[PipRequirement] | None = Field(None, description="Optional list of pip packages required by this tool.")npm_requirements: list[NpmRequirement] | None = Field(None, description="Optional list of npm packages required by this tool.")+++class ToolSearchRequest(LettaBase):+ """Request model for searching tools using semantic search."""++ query: Optional[str] = Field(None, description="Text query for semantic search.")+ search_mode: Literal["vector", "fts", "hybrid"] = Field("hybrid", description="Search mode: vector, fts, or hybrid.")+ tool_types: Optional[List[str]] = Field(None, description="Filter by tool types (e.g., 'custom', 'letta_core').")+ tags: Optional[List[str]] = Field(None, description="Filter by tags (match any).")+ limit: int = Field(50, description="Maximum number of results to return.", ge=1, le=100)+++class ToolSearchResult(LettaBase):+ """Result from a tool search operation."""++ tool: Tool = Field(..., description="The matched tool.")+ embedded_text: Optional[str] = Field(None, description="The embedded text content used for matching.")+ fts_rank: Optional[int] = Field(None, description="Full-text search rank position.")+ vector_rank: Optional[int] = Field(None, description="Vector search rank position.")+ combined_score: float = Field(..., description="Combined relevance score (RRF for hybrid mode).")diff --git a/letta/server/rest_api/routers/v1/tools.py b/letta/server/rest_api/routers/v1/tools.pyindex edd4c83ad..fbe989a97 100644--- a/letta/server/rest_api/routers/v1/tools.py+++ b/letta/server/rest_api/routers/v1/tools.py@@ -31,7 +31,7 @@ from letta.schemas.letta_message_content import TextContentfrom letta.schemas.mcp import UpdateSSEMCPServer, UpdateStdioMCPServer, UpdateStreamableHTTPMCPServerfrom letta.schemas.message import Messagefrom letta.schemas.pip_requirement import PipRequirement-from letta.schemas.tool import BaseTool, Tool, ToolCreate, ToolRunFromSource, ToolUpdate+from letta.schemas.tool import BaseTool, Tool, ToolCreate, ToolRunFromSource, ToolSearchRequest, ToolSearchResult, ToolUpdatefrom letta.server.rest_api.dependencies import HeaderParams, get_headers, get_letta_serverfrom letta.server.rest_api.streaming_response import StreamingResponseWithStatusCodefrom letta.server.server import SyncServer@@ -271,6 +271,46 @@ async def list_tools()[email protected]("/search", response_model=List[ToolSearchResult], operation_id="search_tools")+async def search_tools(+ request: ToolSearchRequest = Body(...),+ server: SyncServer = Depends(get_letta_server),+ headers: HeaderParams = Depends(get_headers),+):+ """+ Search tools using semantic search.++ Requires tool embedding to be enabled (embed_tools=True). Uses vector search,+ full-text search, or hybrid mode to find tools matching the query.++ Returns tools ranked by relevance with their search scores.+ """+ actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)++ try:+ results = await server.tool_manager.search_tools_async(+ actor=actor,+ query_text=request.query,+ search_mode=request.search_mode,+ tool_types=request.tool_types,+ tags=request.tags,+ limit=request.limit,+ )++ return [+ ToolSearchResult(+ tool=tool,+ embedded_text=None, # Could be populated if needed+ fts_rank=metadata.get("fts_rank"),+ vector_rank=metadata.get("vector_rank"),+ combined_score=metadata.get("combined_score", 0.0),+ )+ for tool, metadata in results+ ]+ except ValueError as e:+ raise HTTPException(status_code=400, detail=str(e))++@router.post("/", response_model=Tool, operation_id="create_tool")async def create_tool(request: ToolCreate = Body(...),diff --git a/letta/services/tool_manager.py b/letta/services/tool_manager.pyindex 5674e8016..98f5a19ff 100644--- a/letta/services/tool_manager.py+++ b/letta/services/tool_manager.py@@ -41,7 +41,7 @@ from letta.services.helpers.agent_manager_helper import calculate_multi_agent_tofrom letta.services.mcp.types import SSEServerConfig, StdioServerConfigfrom letta.services.tool_schema_generator import generate_schema_for_tool_creation, generate_schema_for_tool_updatefrom letta.settings import settings, tool_settings-from letta.utils import enforce_types, printd+from letta.utils import enforce_types, fire_and_forget, printdfrom letta.validators import raise_on_invalid_idlogger = get_logger(__name__)@@ -338,6 +338,15 @@ class ToolManager:if created_tool.tool_type == ToolType.CUSTOM and tool_requests_modal and modal_configured:await self.create_or_update_modal_app(created_tool, actor)+ # Embed tool in Turbopuffer if enabled+ from letta.helpers.tpuf_client import should_use_tpuf_for_tools++ if should_use_tpuf_for_tools():+ fire_and_forget(+ self._embed_tool_background(created_tool, actor),+ task_name=f"embed_tool_{created_tool.id}",+ )+return created_tool@enforce_types@@ -869,6 +878,28 @@ class ToolManager:logger.info(f"Deploying Modal app for tool {updated_tool.id} with new hash: {new_hash}")await self.create_or_update_modal_app(updated_tool, actor)+ # Update embedding in Turbopuffer if enabled (delete old, insert new)+ from letta.helpers.tpuf_client import should_use_tpuf_for_tools++ if should_use_tpuf_for_tools():++ async def update_tool_embedding():+ try:+ from letta.helpers.tpuf_client import TurbopufferClient++ tpuf_client = TurbopufferClient()+ # Delete old and re-insert (simpler than update)+ await tpuf_client.delete_tools(actor.organization_id, [updated_tool.id])+ await tpuf_client.insert_tools([updated_tool], actor.organization_id, actor)+ logger.info(f"Successfully updated tool {updated_tool.id} in Turbopuffer")+ except Exception as e:+ logger.error(f"Failed to update tool {updated_tool.id} in Turbopuffer: {e}")++ fire_and_forget(+ update_tool_embedding(),+ task_name=f"update_tool_embedding_{updated_tool.id}",+ )+return updated_tool@enforce_types@@ -901,6 +932,20 @@ class ToolManager:logger.warning(f"Skipping Modal cleanup for corrupted tool {tool_id}: {e}")await tool.hard_delete_async(db_session=session, actor=actor)++ # Delete from Turbopuffer if enabled+ from letta.helpers.tpuf_client import should_use_tpuf_for_tools++ if should_use_tpuf_for_tools():+ try:+ from letta.helpers.tpuf_client import TurbopufferClient++ tpuf_client = TurbopufferClient()+ await tpuf_client.delete_tools(actor.organization_id, [tool_id])+ logger.info(f"Successfully deleted tool {tool_id} from Turbopuffer")+ except Exception as e:+ logger.warning(f"Failed to delete tool {tool_id} from Turbopuffer: {e}")+except NoResultFound:raise ValueError(f"Tool with id {tool_id} not found.")@@ -1121,3 +1166,95 @@ class ToolManager:except Exception as e:logger.error(f"Error during Modal app deletion for tool {tool.name}: {e}")raise++ async def _embed_tool_background(+ self,+ tool: PydanticTool,+ actor: PydanticUser,+ ) -> None:+ """Background task to embed a tool in Turbopuffer.++ Args:+ tool: The tool to embed+ actor: User performing the action+ """+ try:+ from letta.helpers.tpuf_client import TurbopufferClient++ tpuf_client = TurbopufferClient()+ await tpuf_client.insert_tools(+ tools=[tool],+ organization_id=actor.organization_id,+ actor=actor,+ )+ logger.info(f"Successfully embedded tool {tool.id} in Turbopuffer")+ except Exception as e:+ logger.error(f"Failed to embed tool {tool.id} in Turbopuffer: {e}")++ @enforce_types+ @trace_method+ async def search_tools_async(+ self,+ actor: PydanticUser,+ query_text: Optional[str] = None,+ search_mode: str = "hybrid",+ tool_types: Optional[List[str]] = None,+ tags: Optional[List[str]] = None,+ limit: int = 50,+ ) -> List[tuple[PydanticTool, dict]]:+ """+ Search tools using Turbopuffer semantic search.++ Args:+ actor: User performing the search+ query_text: Text query for semantic search+ search_mode: "vector", "fts", or "hybrid" (default: "hybrid")+ tool_types: Optional list of tool types to filter by+ tags: Optional list of tags to filter by+ limit: Maximum number of results to return++ Returns:+ List of (tool, metadata) tuples where metadata contains search scores++ Raises:+ ValueError: If Turbopuffer is not enabled for tools+ """+ from letta.helpers.tpuf_client import TurbopufferClient, should_use_tpuf_for_tools++ if not should_use_tpuf_for_tools():+ raise ValueError("Tool semantic search requires tool embedding to be enabled (embed_tools=True).")++ tpuf_client = TurbopufferClient()+ results = await tpuf_client.query_tools(+ organization_id=actor.organization_id,+ actor=actor,+ query_text=query_text,+ search_mode=search_mode,+ top_k=limit,+ tool_types=tool_types,+ tags=tags,+ )++ if not results:+ return []++ # Fetch full tool objects from database+ tool_ids = [tool_dict["id"] for tool_dict, _, _ in results]+ tools = []+ for tool_id in tool_ids:+ try:+ tool = await self.get_tool_by_id_async(tool_id, actor=actor)+ tools.append(tool)+ except Exception:+ pass # Tool may have been deleted++ tool_map = {tool.id: tool for tool in tools}++ # Build result list preserving order and including metadata+ result_list = []+ for tool_dict, _, metadata in results:+ tool_id = tool_dict["id"]+ if tool_id in tool_map:+ result_list.append((tool_map[tool_id], metadata))++ return result_listdiff --git a/letta/settings.py b/letta/settings.pyindex 71efaed53..9f929eeb8 100644--- a/letta/settings.py+++ b/letta/settings.py@@ -334,6 +334,7 @@ class Settings(BaseSettings):tpuf_api_key: Optional[str] = Nonetpuf_region: str = "gcp-us-central1"embed_all_messages: bool = False+ embed_tools: bool = False# For encryptionencryption_key: Optional[str] = Nonediff --git a/tests/sdk/search_test.py b/tests/sdk/search_test.pyindex 67bfab498..d167af41e 100644--- a/tests/sdk/search_test.py+++ b/tests/sdk/search_test.py@@ -16,6 +16,7 @@ from letta_client.types import CreateBlockParam, MessageCreateParamfrom letta.config import LettaConfigfrom letta.schemas.message import MessageSearchResult+from letta.schemas.tool import ToolSearchResultfrom letta.server.rest_api.routers.v1.passages import PassageSearchResultfrom letta.server.server import SyncServerfrom letta.settings import model_settings, settings@@ -53,6 +54,34 @@ def cleanup_agent_with_messages(client: Letta, agent_id: str):print(f"Warning: Failed to clean up agent {agent_id}: {e}")+def cleanup_tool(client: Letta, tool_id: str):+ """+ Helper function to properly clean up a tool by deleting it from both+ Turbopuffer and the database.++ Args:+ client: Letta SDK client+ tool_id: ID of the tool to clean up+ """+ try:+ # First, delete from Turbopuffer if tool embedding is enabled+ try:+ import asyncio++ from letta.helpers.tpuf_client import TurbopufferClient, should_use_tpuf_for_tools++ if should_use_tpuf_for_tools():+ tpuf_client = TurbopufferClient()+ asyncio.run(tpuf_client.delete_tools(DEFAULT_ORG_ID, [tool_id]))+ except Exception as e:+ print(f"Warning: Failed to clean up Turbopuffer tool {tool_id}: {e}")++ # Now delete the tool from the database+ client.tools.delete(tool_id=tool_id)+ except Exception as e:+ print(f"Warning: Failed to clean up tool {tool_id}: {e}")++@pytest.fixture(scope="module")def server():"""Server fixture for testing"""@@ -524,3 +553,163 @@ def test_passage_search_org_wide(client: Letta, enable_turbopuffer):# Clean up agentscleanup_agent_with_messages(client, agent1.id)cleanup_agent_with_messages(client, agent2.id)+++def enable_tool_embedding():+ """Enable both Turbopuffer and tool embedding"""+ original_use_tpuf = settings.use_tpuf+ original_api_key = settings.tpuf_api_key+ original_embed_tools = settings.embed_tools+ original_environment = settings.environment++ settings.use_tpuf = True+ settings.tpuf_api_key = settings.tpuf_api_key or "test-key"+ settings.embed_tools = True+ settings.environment = "DEV"++ yield++ settings.use_tpuf = original_use_tpuf+ settings.tpuf_api_key = original_api_key+ settings.embed_tools = original_embed_tools+ settings.environment = original_environment+++ not (settings.use_tpuf and settings.tpuf_api_key and model_settings.openai_api_key and settings.embed_tools),+ reason="Tool search requires Turbopuffer, OpenAI, and tool embedding to be enabled",+)+def test_tool_search_basic(client: Letta, enable_tool_embedding):+ """Test basic tool search functionality through the SDK"""+ tool_ids = []++ try:+ # Create test tools with distinct descriptions for semantic search+ test_tools = [+ {+ "source_code": '''+def send_email_to_user(recipient: str, subject: str, body: str) -> str:+ """Send an email message to a specified recipient.++ Args:+ recipient: Email address of the recipient+ subject: Subject line of the email+ body: Body content of the email message++ Returns:+ Confirmation message+ """+ return f"Email sent to {recipient}"+''',+ "description": "Send an email message to a specified recipient with subject and body.",+ "tags": ["communication", "email"],+ },+ {+ "source_code": '''+def fetch_weather_data(city: str, units: str = "celsius") -> str:+ """Fetch current weather information for a city.++ Args:+ city: Name of the city to get weather for+ units: Temperature units (celsius or fahrenheit)++ Returns:+ Weather information string+ """+ return f"Weather in {city}: sunny, 25 {units}"+''',+ "description": "Fetch current weather information for a specified city.",+ "tags": ["weather", "api"],+ },+ {+ "source_code": '''+def calculate_compound_interest(principal: float, rate: float, years: int) -> float:+ """Calculate compound interest on an investment.++ Args:+ principal: Initial investment amount+ rate: Annual interest rate as decimal+ years: Number of years++ Returns:+ Final amount after compound interest+ """+ return principal * (1 + rate) ** years+''',+ "description": "Calculate compound interest on a financial investment over time.",+ "tags": ["finance", "calculator"],+ },+ ]++ # Create tools via SDK+ for tool_data in test_tools:+ tool = client.tools.create(+ source_code=tool_data["source_code"],+ description=tool_data["description"],+ tags=tool_data["tags"],+ )+ tool_ids.append(tool.id)++ # Wait for embeddings to be indexed+ time.sleep(3)++ # Test semantic search - should find email-related tool+ results = client.post(+ "/v1/tools/search",+ cast_to=list[ToolSearchResult],+ body={+ "query": "send message to someone",+ "search_mode": "hybrid",+ "limit": 10,+ },+ )++ assert len(results) > 0, "Should find at least one tool"++ # The email tool should be ranked highly for this query+ tool_names = [result["tool"]["name"] for result in results]+ assert "send_email_to_user" in tool_names, "Should find email tool for messaging query"++ # Verify result structure+ for result in results:+ assert "tool" in result, "Result should have tool field"+ assert "combined_score" in result, "Result should have combined_score field"+ assert isinstance(result["combined_score"], float), "combined_score should be a float"++ # Test search with different query - should find weather tool+ weather_results = client.post(+ "/v1/tools/search",+ cast_to=list[ToolSearchResult],+ body={+ "query": "get temperature forecast",+ "search_mode": "hybrid",+ "limit": 10,+ },+ )++ assert len(weather_results) > 0, "Should find tools for weather query"+ weather_tool_names = [result["tool"]["name"] for result in weather_results]+ assert "fetch_weather_data" in weather_tool_names, "Should find weather tool"++ # Test search with tag filter+ finance_results = client.post(+ "/v1/tools/search",+ cast_to=list[ToolSearchResult],+ body={+ "query": "money calculation",+ "tags": ["finance"],+ "search_mode": "hybrid",+ "limit": 10,+ },+ )++ # Should find the finance tool when filtering by tag+ if len(finance_results) > 0:+ finance_tool_names = [result["tool"]["name"] for result in finance_results]+ assert "calculate_compound_interest" in finance_tool_names, "Should find finance tool with tag filter"++ finally:+ # Clean up all created tools+ for tool_id in tool_ids:+ cleanup_tool(client, tool_id)