refactor search to make it aligned to the defender and future

Author: shashi-stackone

examples/search_tool_example.py

@@ -62,38 +62,52 @@ def example_search_tool_basic():
 def example_search_modes():
     """Comparing semantic vs local search modes.
 
-    The search parameter controls which backend search_tools() uses:
+    Search config can be set at the constructor level or overridden per call:
+    - Constructor: StackOneToolSet(search={"method": "semantic"})
+    - Per-call: toolset.search_tools(query, search="local")
+
+    The search method controls which backend search_tools() uses:
     - "semantic": cloud-based semantic vector search (higher accuracy for natural language)
     - "local": local BM25+TF-IDF hybrid search (no network call to semantic API)
     - "auto" (default): tries semantic first, falls back to local on failure
     """
     print("Example 2: Semantic vs local search modes\n")
 
-    toolset = StackOneToolSet()
     query = "manage employee time off"
 
-    # Semantic search — uses StackOne's semantic search API
-    print('search="semantic": cloud-based semantic vector search')
+    # Constructor-level config — semantic search as the default for this toolset
+    print('Constructor config: StackOneToolSet(search={"method": "semantic"})')
+    toolset_semantic = StackOneToolSet(search={"method": "semantic"})
     try:
-        tools_semantic = toolset.search_tools(query, account_ids=_account_ids, top_k=5, search="semantic")
+        tools_semantic = toolset_semantic.search_tools(query, account_ids=_account_ids, top_k=5)
         print(f"  Found {len(tools_semantic)} tools:")
         for tool in tools_semantic:
             print(f"    - {tool.name}")
     except Exception as e:
         print(f"  Semantic search unavailable: {e}")
     print()
 
-    # Local search — BM25+TF-IDF, no semantic API call
-    print('search="local": local BM25+TF-IDF hybrid search')
-    tools_local = toolset.search_tools(query, account_ids=_account_ids, top_k=5, search="local")
+    # Constructor-level config — local search (no network call to semantic API)
+    print('Constructor config: StackOneToolSet(search={"method": "local"})')
+    toolset_local = StackOneToolSet(search={"method": "local"})
+    tools_local = toolset_local.search_tools(query, account_ids=_account_ids, top_k=5)
     print(f"  Found {len(tools_local)} tools:")
     for tool in tools_local:
         print(f"    - {tool.name}")
     print()
 
+    # Per-call override — constructor defaults can be overridden on each call
+    print("Per-call override: constructor uses semantic, but this call uses local")
+    tools_override = toolset_semantic.search_tools(query, account_ids=_account_ids, top_k=5, search="local")
+    print(f"  Found {len(tools_override)} tools:")
+    for tool in tools_override:
+        print(f"    - {tool.name}")
+    print()
+
     # Auto (default) — tries semantic, falls back to local
-    print('search="auto" (default): semantic with local fallback')
-    tools_auto = toolset.search_tools(query, account_ids=_account_ids, top_k=5, search="auto")
+    print('Default: StackOneToolSet() uses search="auto" (semantic with local fallback)')
+    toolset_auto = StackOneToolSet()
+    tools_auto = toolset_auto.search_tools(query, account_ids=_account_ids, top_k=5)
     print(f"  Found {len(tools_auto)} tools:")
     for tool in tools_auto:
         print(f"    - {tool.name}")

examples/semantic_search_example.py

@@ -110,7 +110,9 @@ def example_search_action_names():
     print("No account ID needed — results come from all available connectors.")
     print()
 
-    toolset = StackOneToolSet()
+    # Constructor-level config sets defaults; per-call params override them.
+    # Here we set method="semantic" at the constructor level.
+    toolset = StackOneToolSet(search={"method": "semantic"})
 
     query = "get user schedule"
 
@@ -156,19 +158,25 @@ def example_search_tools():
     2. Searches each of your connectors in parallel via the semantic search API
     3. Sorts results by relevance and matches back to tool definitions
     4. Returns a Tools collection ready for any framework (.to_openai(), .to_langchain(), etc.)
+
+    Search config can be set at the constructor level:
+        toolset = StackOneToolSet(search={"method": "semantic", "top_k": 5})
+    Per-call parameters (e.g. top_k, search) override the constructor defaults.
     """
     print("=" * 60)
     print("Example 2: search_tools() — full tool discovery")
     print("=" * 60)
     print()
 
-    toolset = StackOneToolSet()
+    # Constructor-level search config: always use semantic search with top_k=5
+    toolset = StackOneToolSet(search={"method": "semantic", "top_k": 5})
 
     query = "cancel an event"
-    print(f'Step 1: Searching for "{query}" via semantic search...')
+    print(f'Step 1: Searching for "{query}" via semantic search (constructor config)...')
     print()
 
-    tools = toolset.search_tools(query, account_ids=_account_ids, top_k=5)
+    # top_k and method are already set via the constructor — no need to pass them here
+    tools = toolset.search_tools(query, account_ids=_account_ids)
 
     connectors = tools.get_connectors()
     print(f"Found {len(tools)} tools from your linked account(s) ({', '.join(sorted(connectors))}):")

stackone_ai/__init__.py

@@ -7,12 +7,13 @@
     SemanticSearchResponse,
     SemanticSearchResult,
 )
-from stackone_ai.toolset import SearchMode, SearchTool, StackOneToolSet
+from stackone_ai.toolset import SearchConfig, SearchMode, SearchTool, StackOneToolSet
 
 __all__ = [
     "StackOneToolSet",
     "StackOneTool",
     "Tools",
+    "SearchConfig",
     "SearchMode",
     "SearchTool",
     # Semantic search