Update the client to use PR suggested client and use min_similarity from the server

Author: shashi-stackone

examples/semantic_search_example.py

@@ -226,19 +226,17 @@ def example_utility_tools_semantic():
     print("  Pass semantic_client=toolset.semantic_client to enable semantic search.")
     utility = tools.utility_tools(semantic_client=toolset.semantic_client)
 
-    search_tool = utility.get_tool("tool_search")
-    if search_tool:
-        query = "cancel an event or meeting"
-        print()
-        print(f'Step 3: Calling tool_search with query="{query}"...')
-        print("  (Searches are scoped to your linked connectors)")
-        print()
-        result = search_tool.call(query=query, limit=5)
-        tools_data = result.get("tools", [])
-        print(f"tool_search returned {len(tools_data)} results:")
-        for tool_info in tools_data:
-            print(f"  [{tool_info['score']:.2f}] {tool_info['name']}")
-            print(f"         {tool_info['description']}")
+    query = "cancel an event or meeting"
+    print()
+    print(f'Step 3: Calling tool_search with query="{query}"...')
+    print("  (Searches are scoped to your linked connectors)")
+    print()
+    result = utility.search_tool.call(query=query, limit=5)
+    tools_data = result.get("tools", [])
+    print(f"tool_search returned {len(tools_data)} results:")
+    for tool_info in tools_data:
+        print(f"  [{tool_info['score']:.2f}] {tool_info['name']}")
+        print(f"         {tool_info['description']}")
 
     print()
 

examples/utility_tools_example.py

@@ -4,6 +4,16 @@
 
 Utility tools allow AI agents to search for relevant tools based on natural language queries
 and execute them dynamically without hardcoding tool names.
+
+Prerequisites:
+- STACKONE_API_KEY environment variable set
+- STACKONE_ACCOUNT_ID environment variable set (comma-separated for multiple)
+- At least one linked account in StackOne (this example uses BambooHR)
+
+This example is runnable with the following command:
+```bash
+uv run examples/utility_tools_example.py
+```
 """
 
 import os
@@ -15,6 +25,9 @@
 # Load environment variables
 load_dotenv()
 
+# Read account IDs from environment — supports comma-separated values
+_account_ids = [aid.strip() for aid in os.getenv("STACKONE_ACCOUNT_ID", "").split(",") if aid.strip()]
+
 
 def example_utility_tools_basic():
     """Basic example of using utility tools for tool discovery"""
@@ -24,21 +37,22 @@ def example_utility_tools_basic():
     toolset = StackOneToolSet()
 
     # Get all available tools using MCP-backed fetch_tools()
-    all_tools = toolset.fetch_tools(actions=["bamboohr_*"])
-    print(f"Total BambooHR tools available: {len(all_tools)}")
+    all_tools = toolset.fetch_tools(account_ids=_account_ids)
+    print(f"Total tools available: {len(all_tools)}")
+
+    if not all_tools:
+        print("No tools found. Check your linked accounts.")
+        return
 
     # Get utility tools for dynamic discovery
     utility_tools = all_tools.utility_tools()
 
-    # Get the filter tool to search for relevant tools
-    filter_tool = utility_tools.get_tool("tool_search")
-    if filter_tool:
-        # Search for employee management tools
-        result = filter_tool.call(query="manage employees create update list", limit=5, minScore=0.0)
+    # Search for employee management tools
+    result = utility_tools.search_tool.call(query="manage employees create update list", limit=5)
 
-        print("Found relevant tools:")
-        for tool in result.get("tools", []):
-            print(f"  - {tool['name']} (score: {tool['score']:.2f}): {tool['description']}")
+    print("Found relevant tools:")
+    for tool in result.get("tools", []):
+        print(f"  - {tool['name']} (score: {tool['score']:.2f}): {tool['description']}")
 
     print()
 
@@ -51,31 +65,31 @@ def example_utility_tools_with_execution():
     toolset = StackOneToolSet()
 
     # Get all tools using MCP-backed fetch_tools()
-    all_tools = toolset.fetch_tools()
+    all_tools = toolset.fetch_tools(account_ids=_account_ids)
+
+    if not all_tools:
+        print("No tools found. Check your linked accounts.")
+        return
+
     utility_tools = all_tools.utility_tools()
 
     # Step 1: Search for relevant tools
-    filter_tool = utility_tools.get_tool("tool_search")
-    execute_tool = utility_tools.get_tool("tool_execute")
-
-    if filter_tool and execute_tool:
-        # Find tools for listing employees
-        search_result = filter_tool.call(query="list all employees", limit=1)
-
-        tools_found = search_result.get("tools", [])
-        if tools_found:
-            best_tool = tools_found[0]
-            print(f"Best matching tool: {best_tool['name']}")
-            print(f"Description: {best_tool['description']}")
-            print(f"Relevance score: {best_tool['score']:.2f}")
-
-            # Step 2: Execute the found tool
-            try:
-                print(f"\nExecuting {best_tool['name']}...")
-                result = execute_tool.call(toolName=best_tool["name"], params={"limit": 5})
-                print(f"Execution result: {result}")
-            except Exception as e:
-                print(f"Execution failed (expected in example): {e}")
+    search_result = utility_tools.search_tool.call(query="list all employees", limit=1)
+
+    tools_found = search_result.get("tools", [])
+    if tools_found:
+        best_tool = tools_found[0]
+        print(f"Best matching tool: {best_tool['name']}")
+        print(f"Description: {best_tool['description']}")
+        print(f"Relevance score: {best_tool['score']:.2f}")
+
+        # Step 2: Execute the found tool
+        try:
+            print(f"\nExecuting {best_tool['name']}...")
+            result = utility_tools.execute_tool.call(toolName=best_tool["name"], params={"limit": 5})
+            print(f"Execution result: {result}")
+        except Exception as e:
+            print(f"Execution failed (expected in example): {e}")
 
     print()
 
@@ -94,7 +108,7 @@ def example_with_openai():
         toolset = StackOneToolSet()
 
         # Get BambooHR tools and their utility tools using MCP-backed fetch_tools()
-        bamboohr_tools = toolset.fetch_tools(actions=["bamboohr_*"])
+        bamboohr_tools = toolset.fetch_tools(account_ids=_account_ids, actions=["bamboohr_*"])
         utility_tools = bamboohr_tools.utility_tools()
 
         # Convert to OpenAI format
@@ -142,7 +156,7 @@ def example_with_langchain():
         toolset = StackOneToolSet()
 
         # Get tools and convert to LangChain format using MCP-backed fetch_tools()
-        tools = toolset.fetch_tools(actions=["bamboohr_list_*"])
+        tools = toolset.fetch_tools(account_ids=_account_ids, actions=["bamboohr_list_*"])
         langchain_tools = tools.to_langchain()
 
         # Get utility tools as well
@@ -194,6 +208,15 @@ def main():
     print("=" * 60)
     print()
 
+    if not os.getenv("STACKONE_API_KEY"):
+        print("Set STACKONE_API_KEY to run these examples.")
+        return
+
+    if not _account_ids:
+        print("Set STACKONE_ACCOUNT_ID to run these examples.")
+        print("(Comma-separated for multiple accounts)")
+        return
+
     # Basic examples that work without external APIs
     example_utility_tools_basic()
     example_utility_tools_with_execution()

stackone_ai/__init__.py

@@ -1,6 +1,6 @@
 """StackOne AI SDK"""
 
-from stackone_ai.models import StackOneTool, Tools
+from stackone_ai.models import StackOneTool, Tools, UtilityTools
 from stackone_ai.semantic_search import (
     SemanticSearchClient,
     SemanticSearchError,
@@ -13,6 +13,7 @@
     "StackOneToolSet",
     "StackOneTool",
     "Tools",
+    "UtilityTools",
     # Semantic search
     "SemanticSearchClient",
     "SemanticSearchResult",

stackone_ai/models.py

@@ -561,7 +561,7 @@ def utility_tools(
         self,
         hybrid_alpha: float | None = None,
         semantic_client: SemanticSearchClient | None = None,
-    ) -> Tools:
+    ) -> UtilityTools:
         """Return utility tools for tool discovery and execution
 
         Utility tools enable dynamic tool discovery and execution based on natural language queries.
@@ -576,7 +576,7 @@ def utility_tools(
                 toolset.semantic_client to enable cloud-based semantic search.
 
         Returns:
-            Tools collection containing tool_search and tool_execute
+            UtilityTools collection with search_tool and execute_tool accessors
 
         Note:
             This feature is in beta and may change in future versions
@@ -586,9 +586,11 @@ def utility_tools(
             toolset = StackOneToolSet()
             tools = toolset.fetch_tools()
             utility = tools.utility_tools(semantic_client=toolset.semantic_client)
+            result = utility.search_tool.call(query="onboard new hire")
 
             # Local BM25+TF-IDF search (default, no semantic_client)
             utility = tools.utility_tools()
+            result = utility.search_tool.call(query="onboard new hire")
         """
         from stackone_ai.utility_tools import create_tool_execute
 
@@ -599,7 +601,7 @@ def utility_tools(
                 semantic_client, available_connectors=self.get_connectors()
             )
             execute_tool = create_tool_execute(self)
-            return Tools([search_tool, execute_tool])
+            return UtilityTools([search_tool, execute_tool])
 
         # Default: local BM25+TF-IDF search
         from stackone_ai.utility_tools import ToolIndex, create_tool_search
@@ -608,4 +610,38 @@ def utility_tools(
         filter_tool = create_tool_search(index)
         execute_tool = create_tool_execute(self)
 
-        return Tools([filter_tool, execute_tool])
+        return UtilityTools([filter_tool, execute_tool])
+
+
+class UtilityTools(Tools):
+    """Utility tools collection with typed accessors for search and execute tools."""
+
+    @property
+    def search_tool(self) -> StackOneTool:
+        """Get the tool_search utility tool.
+
+        Returns:
+            The tool_search tool for discovering relevant tools
+
+        Raises:
+            StackOneError: If tool_search is not found in the collection
+        """
+        tool = self.get_tool("tool_search")
+        if tool is None:
+            raise StackOneError("tool_search not found in this UtilityTools collection")
+        return tool
+
+    @property
+    def execute_tool(self) -> StackOneTool:
+        """Get the tool_execute utility tool.
+
+        Returns:
+            The tool_execute tool for running discovered tools
+
+        Raises:
+            StackOneError: If tool_execute is not found in the collection
+        """
+        tool = self.get_tool("tool_execute")
+        if tool is None:
+            raise StackOneError("tool_execute not found in this UtilityTools collection")
+        return tool

stackone_ai/semantic_search.py

@@ -133,6 +133,7 @@ def search(
         connector: str | None = None,
         top_k: int | None = None,
         project_id: str | None = None,
+        min_similarity: float | None = None,
     ) -> SemanticSearchResponse:
         """Search for relevant actions using semantic search.
 
@@ -142,6 +143,8 @@ def search(
             top_k: Maximum number of results to return. If not provided, uses the backend default.
             project_id: Optional project scope (e.g., "103/dev-56501"). When provided,
                 results include both global actions and project-specific actions.
+            min_similarity: Minimum similarity score threshold (0-1). If not provided,
+                the server uses its default (currently 0.4).
 
         Returns:
             SemanticSearchResponse containing matching actions with similarity scores
@@ -166,6 +169,8 @@ def search(
             payload["connector"] = connector
         if project_id:
             payload["project_id"] = project_id
+        if min_similarity is not None:
+            payload["min_similarity"] = min_similarity
 
         try:
             response = httpx.post(url, json=payload, headers=headers, timeout=self.timeout)
@@ -184,7 +189,7 @@ def search_action_names(
         query: str,
         connector: str | None = None,
         top_k: int | None = None,
-        min_score: float = 0.0,
+        min_similarity: float | None = None,
         project_id: str | None = None,
     ) -> list[str]:
         """Convenience method returning just action names.
@@ -193,7 +198,8 @@ def search_action_names(
             query: Natural language query
             connector: Optional connector/provider filter
             top_k: Maximum number of results. If not provided, uses the backend default.
-            min_score: Minimum similarity score threshold (0-1)
+            min_similarity: Minimum similarity score threshold (0-1). If not provided,
+                the server uses its default.
             project_id: Optional project scope for multi-tenant filtering
 
         Returns:
@@ -203,8 +209,8 @@ def search_action_names(
             action_names = client.search_action_names(
                 "create employee",
                 connector="bamboohr",
-                min_score=0.5
+                min_similarity=0.5
             )
         """
-        response = self.search(query, connector, top_k, project_id)
-        return [r.action_name for r in response.results if r.similarity_score >= min_score]
+        response = self.search(query, connector, top_k, project_id, min_similarity=min_similarity)
+        return [r.action_name for r in response.results]