Implement PR sugggestions and use the search and execute tools as standard way

Author: shashi-stackone

README.md

@@ -318,12 +318,10 @@ tools = toolset.fetch_tools(actions=["hris_*"])
 utility_tools = tools.utility_tools()
 
 # Search for relevant tools using natural language
-filter_tool = utility_tools.get_tool("tool_search")
-results = filter_tool.call(query="manage employees", limit=5)
+results = utility_tools.search_tool.call(query="manage employees", limit=5)
 
 # Execute discovered tools dynamically
-execute_tool = utility_tools.get_tool("tool_execute")
-result = execute_tool.call(toolName="hris_list_employees", params={"limit": 10})
+result = utility_tools.execute_tool.call(toolName="hris_list_employees", params={"limit": 10})
 ```
 
 ## Semantic Search

examples/semantic_search_example.py

@@ -30,6 +30,10 @@
    f) Match results back to the fetched tool definitions
    g) Return a Tools collection sorted by relevance score
 
+   Tip: when you know which provider the user works with, pass
+   ``connector="calendly"`` to scope the search to a single connector —
+   this is faster and returns more relevant results.
+
    Key point: only the user's own connectors are searched — no wasted results
    from connectors the user doesn't have. When top_k is not specified, the
    backend decides how many results to return per connector. If the semantic
@@ -46,11 +50,11 @@
 3. utility_tools()  — Agent-loop pattern
 
    Creates tool_search and tool_execute utility tools that agents can call
-   inside an agentic loop. Pass semantic_client=toolset.semantic_client to
-   enable cloud-based semantic search; without it, local BM25+TF-IDF is
-   used. When created via utility_tools(), tool_search is automatically
-   scoped to the user's linked connectors. The agent searches, inspects,
-   and executes tools dynamically.
+   inside an agentic loop. Pass search_method="semantic" to enable
+   cloud-based semantic search; without it, local BM25+TF-IDF is used.
+   When created via utility_tools(), tool_search is automatically scoped
+   to the user's linked connectors. The agent searches, inspects, and
+   executes tools dynamically.
 
 
 This example is runnable with the following command:
@@ -69,11 +73,14 @@
 import logging
 import os
 
-from dotenv import load_dotenv
-
 from stackone_ai import StackOneToolSet
 
-load_dotenv()
+try:
+    from dotenv import load_dotenv
+
+    load_dotenv()
+except ModuleNotFoundError:
+    pass
 
 # Show SDK warnings (e.g., semantic search fallback to local search)
 logging.basicConfig(level=logging.WARNING)
@@ -203,9 +210,9 @@ def example_search_tools_with_connector():
 def example_utility_tools_semantic():
     """Using utility tools with semantic search for agent loops.
 
-    Pass semantic_client=toolset.semantic_client to utility_tools() to enable
-    cloud-based semantic search. Without it, utility_tools() uses local
-    BM25+TF-IDF search instead.
+    Pass search_method="semantic" to utility_tools() to enable cloud-based
+    semantic search. Without it, utility_tools() uses local BM25+TF-IDF
+    search instead.
 
     When created via utility_tools(), tool_search is automatically scoped to
     the connectors available in your fetched tools collection.
@@ -223,8 +230,8 @@ def example_utility_tools_semantic():
     print()
 
     print("Step 2: Creating utility tools with semantic search enabled...")
-    print("  Pass semantic_client=toolset.semantic_client to enable semantic search.")
-    utility = tools.utility_tools(semantic_client=toolset.semantic_client)
+    print('  Pass search_method="semantic" to enable cloud-based semantic search.')
+    utility = tools.utility_tools(search_method="semantic")
 
     query = "cancel an event or meeting"
     print()

examples/utility_tools_example.py

@@ -18,12 +18,14 @@
 
 import os
 
-from dotenv import load_dotenv
-
 from stackone_ai import StackOneToolSet
 
-# Load environment variables
-load_dotenv()
+try:
+    from dotenv import load_dotenv
+
+    load_dotenv()
+except ModuleNotFoundError:
+    pass
 
 # 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()]

stackone_ai/models.py

@@ -469,14 +469,19 @@ def get_account_id(self) -> str | None:
 class Tools:
     """Container for Tool instances with lookup capabilities"""
 
-    def __init__(self, tools: list[StackOneTool]) -> None:
+    def __init__(
+        self,
+        tools: list[StackOneTool],
+        _semantic_client: SemanticSearchClient | None = None,
+    ) -> None:
         """Initialize Tools container
 
         Args:
             tools: List of Tool instances to manage
         """
         self.tools = tools
         self._tool_map = {tool.name: tool for tool in tools}
+        self._semantic_client = _semantic_client
 
     def __getitem__(self, index: int) -> StackOneTool:
         return self.tools[index]
@@ -559,58 +564,69 @@ def to_langchain(self) -> Sequence[BaseTool]:
 
     def utility_tools(
         self,
+        search_method: str = "bm25",
         hybrid_alpha: float | None = None,
-        semantic_client: SemanticSearchClient | None = None,
     ) -> UtilityTools:
         """Return utility tools for tool discovery and execution
 
         Utility tools enable dynamic tool discovery and execution based on natural language queries.
-        By default, uses local hybrid BM25 + TF-IDF search. When a semantic_client is provided,
-        uses cloud-based semantic search for higher accuracy on natural language queries.
+        Choose the search method via ``search_method``:
+
+        - ``"bm25"`` (default) — local hybrid BM25 + TF-IDF search, no network calls.
+        - ``"semantic"`` — cloud-based semantic vector search for higher accuracy on
+          natural language queries. Requires tools fetched via ``StackOneToolSet``.
 
         Args:
+            search_method: Search backend to use. ``"bm25"`` for local search,
+                ``"semantic"`` for cloud-based semantic search.
             hybrid_alpha: Weight for BM25 in hybrid search (0-1). Only used when
-                semantic_client is not provided. If not provided, uses DEFAULT_HYBRID_ALPHA (0.2),
-                which gives more weight to BM25 scoring.
-            semantic_client: Optional SemanticSearchClient instance. Pass
-                toolset.semantic_client to enable cloud-based semantic search.
+                search_method is ``"bm25"``. If not provided, uses DEFAULT_HYBRID_ALPHA (0.2).
 
         Returns:
             UtilityTools collection with search_tool and execute_tool accessors
 
+        Raises:
+            StackOneError: If ``search_method="semantic"`` but tools were not created
+                via ``StackOneToolSet`` (no semantic client available).
+            ValueError: If ``search_method`` is not ``"bm25"`` or ``"semantic"``.
+
         Note:
             This feature is in beta and may change in future versions
 
         Example:
-            # Semantic search (pass semantic_client explicitly)
+            # Semantic search
             toolset = StackOneToolSet()
             tools = toolset.fetch_tools()
-            utility = tools.utility_tools(semantic_client=toolset.semantic_client)
+            utility = tools.utility_tools(search_method="semantic")
             result = utility.search_tool.call(query="onboard new hire")
 
-            # Local BM25+TF-IDF search (default, no semantic_client)
+            # Local BM25+TF-IDF search (default)
             utility = tools.utility_tools()
             result = utility.search_tool.call(query="onboard new hire")
         """
         from stackone_ai.utility_tools import create_tool_execute
 
-        if semantic_client is not None:
+        if search_method == "semantic":
+            if self._semantic_client is None:
+                raise StackOneError(
+                    "Semantic search requires tools fetched via StackOneToolSet. "
+                    "Use toolset.fetch_tools() or toolset.search_tools() first."
+                )
             from stackone_ai.utility_tools import create_semantic_tool_search
 
             search_tool = create_semantic_tool_search(
-                semantic_client, available_connectors=self.get_connectors()
+                self._semantic_client, available_connectors=self.get_connectors()
             )
-            execute_tool = create_tool_execute(self)
-            return UtilityTools([search_tool, execute_tool])
+        elif search_method == "bm25":
+            from stackone_ai.utility_tools import ToolIndex, create_tool_search
 
-        # Default: local BM25+TF-IDF search
-        from stackone_ai.utility_tools import ToolIndex, create_tool_search
+            index = ToolIndex(self.tools, hybrid_alpha=hybrid_alpha)
+            search_tool = create_tool_search(index)
+        else:
+            raise ValueError(f"Unknown search_method: {search_method!r}. Use 'bm25' or 'semantic'.")
 
-        index = ToolIndex(self.tools, hybrid_alpha=hybrid_alpha)
-        filter_tool = create_tool_search(index)
         execute_tool = create_tool_execute(self)
-
-        return UtilityTools([filter_tool, execute_tool])
+        return UtilityTools([search_tool, execute_tool])
 
 
 class UtilityTools(Tools):

stackone_ai/toolset.py

@@ -344,14 +344,14 @@ def search_tools(
         available_connectors = all_tools.get_connectors()
 
         if not available_connectors:
-            return Tools([])
+            return Tools([], _semantic_client=self._semantic_client)
 
         try:
             # Step 2: Determine which connectors to search
             if connector:
                 connectors_to_search = {connector.lower()} & available_connectors
                 if not connectors_to_search:
-                    return Tools([])
+                    return Tools([], _semantic_client=self._semantic_client)
             else:
                 connectors_to_search = available_connectors
 
@@ -383,7 +383,7 @@ def _search_one(c: str) -> list[SemanticSearchResult]:
                 all_results = all_results[:top_k]
 
             if not all_results:
-                return Tools([])
+                return Tools([], _semantic_client=self._semantic_client)
 
             # Step 5: Match back to fetched tool definitions
             action_names = {_normalize_action_name(r.action_name) for r in all_results}
@@ -393,7 +393,7 @@ def _search_one(c: str) -> list[SemanticSearchResult]:
             action_order = {_normalize_action_name(r.action_name): i for i, r in enumerate(all_results)}
             matched_tools.sort(key=lambda t: action_order.get(t.name, float("inf")))
 
-            return Tools(matched_tools)
+            return Tools(matched_tools, _semantic_client=self._semantic_client)
 
         except SemanticSearchError as e:
             if not fallback_to_local:
@@ -420,7 +420,10 @@ def _search_one(c: str) -> list[SemanticSearchResult]:
                     for name in matched_names
                     if name in tool_map and name.split("_")[0].lower() in filter_connectors
                 ]
-                return Tools(matched_tools[:top_k] if top_k is not None else matched_tools)
+                return Tools(
+                    matched_tools[:top_k] if top_k is not None else matched_tools,
+                    _semantic_client=self._semantic_client,
+                )
 
             return all_tools
 
@@ -626,7 +629,7 @@ def fetch_tools(
             if actions:
                 all_tools = [tool for tool in all_tools if self._filter_by_action(tool.name, actions)]
 
-            return Tools(all_tools)
+            return Tools(all_tools, _semantic_client=self.semantic_client)
 
         except ToolsetError:
             raise

tests/test_semantic_search.py

@@ -497,8 +497,9 @@ def test_utility_tools_semantic_search(self) -> None:
             utility = tools.utility_tools()
             assert len(utility) == 2  # tool_search + tool_execute
 
-        # With semantic search - presence of semantic_client enables it
+        # With semantic search - set _semantic_client and use search_method="semantic"
         mock_client = MagicMock(spec=SemanticSearchClient)
+        tools._semantic_client = mock_client
         with (
             patch("stackone_ai.utility_tools.create_semantic_tool_search") as mock_create,
             patch("stackone_ai.utility_tools.create_tool_execute") as mock_create_execute,
@@ -509,7 +510,7 @@ def test_utility_tools_semantic_search(self) -> None:
             mock_execute_tool.name = "tool_execute"
             mock_create.return_value = mock_search_tool
             mock_create_execute.return_value = mock_execute_tool
-            utility = tools.utility_tools(semantic_client=mock_client)
+            utility = tools.utility_tools(search_method="semantic")
             assert len(utility) == 2
             # Should pass available connectors from the tools collection
             mock_create.assert_called_once_with(mock_client, available_connectors={"test"})

tests/test_utility_tools.py

@@ -239,36 +239,36 @@ def test_search_limit_pbt(self, limit: int):
 class TestToolSearch:
     """Test the tool_search functionality"""
 
-    def test_filter_tool_creation(self, sample_tools):
+    def test_search_tool_creation(self, sample_tools):
         """Test creating the filter tool"""
         index = ToolIndex(sample_tools)
-        filter_tool = create_tool_search(index)
+        search_tool = create_tool_search(index)
 
-        assert filter_tool.name == "tool_search"
-        assert "natural language query" in filter_tool.description.lower()
+        assert search_tool.name == "tool_search"
+        assert "natural language query" in search_tool.description.lower()
 
-    def test_filter_tool_execute_with_json_string(self, sample_tools):
+    def test_search_tool_execute_with_json_string(self, sample_tools):
         """Test executing the filter tool with JSON string input."""
         import json
 
         index = ToolIndex(sample_tools)
-        filter_tool = create_tool_search(index)
+        search_tool = create_tool_search(index)
 
         # Execute with JSON string
         json_input = json.dumps({"query": "employee", "limit": 2, "minScore": 0.0})
-        result = filter_tool.execute(json_input)
+        result = search_tool.execute(json_input)
 
         assert "tools" in result
         assert isinstance(result["tools"], list)
         assert len(result["tools"]) <= 2
 
-    def test_filter_tool_execute(self, sample_tools):
+    def test_search_tool_execute(self, sample_tools):
         """Test executing the filter tool"""
         index = ToolIndex(sample_tools)
-        filter_tool = create_tool_search(index)
+        search_tool = create_tool_search(index)
 
         # Execute with a query
-        result = filter_tool.execute(
+        result = search_tool.execute(
             {
                 "query": "manage employees",
                 "limit": 3,
@@ -287,13 +287,13 @@ def test_filter_tool_execute(self, sample_tools):
             assert "description" in tool
             assert "score" in tool
 
-    def test_filter_tool_call(self, sample_tools):
+    def test_search_tool_call(self, sample_tools):
         """Test calling the filter tool with call method"""
         index = ToolIndex(sample_tools)
-        filter_tool = create_tool_search(index)
+        search_tool = create_tool_search(index)
 
         # Call with kwargs
-        result = filter_tool.call(query="candidate", limit=2)
+        result = search_tool.call(query="candidate", limit=2)
 
         assert "tools" in result
         assert len(result["tools"]) <= 2
@@ -377,11 +377,11 @@ def test_utility_tools_functionality(self, tools_collection):
         utility_tools = tools_collection.utility_tools()
 
         # Get the filter tool
-        filter_tool = utility_tools.get_tool("tool_search")
-        assert filter_tool is not None
+        search_tool = utility_tools.get_tool("tool_search")
+        assert search_tool is not None
 
         # Search for tools
-        result = filter_tool.execute(
+        result = search_tool.execute(
             {
                 "query": "create employee",
                 "limit": 1,
@@ -482,13 +482,13 @@ def test_utility_tools_with_custom_alpha(self, sample_tools):
         # Create utility tools with custom alpha
         utility_tools = tools_collection.utility_tools(hybrid_alpha=0.3)
 
-        filter_tool = utility_tools.get_tool("tool_search")
-        assert filter_tool is not None
+        search_tool = utility_tools.get_tool("tool_search")
+        assert search_tool is not None
 
         # Check that description mentions the alpha value
-        assert "alpha=0.3" in filter_tool.description
+        assert "alpha=0.3" in search_tool.description
 
         # Test it works
-        result = filter_tool.execute({"query": "list employees", "limit": 3})
+        result = search_tool.execute({"query": "list employees", "limit": 3})
         assert "tools" in result
         assert len(result["tools"]) > 0