feat(search): Semantic Tool Search

[shashi-stackone]

Problem

Following up from #142

StackOne has over 10,000 actions across all connectors and growing, some connectors have 2,000+ actions alone. Keyword matching breaks
down when someone searches "onboard new hire" but the action is called hris_create_employee. The SDK already supports keyword-based
search, and we need to add semantic search using the action search service.

Implementation Details

• SemanticSearchClient that calls StackOne's /actions/search API for natural language tool discovery
• Three ways to use it:
  1. search_tools() search by intent, get a Tools collection ready for OpenAI, LangChain, or any framework
  2. search_action_names() lightweight lookup returning action names and scores without full tool definitions
  3. Utility tools pass a SemanticSearchClient to utility_tools() and the tool_search tool becomes semantic-aware inside
     agent loops
• Per-connector parallel search so results are scoped to only the connectors the user has linked
• Automatic fallback to local BM25+TF-IDF hybrid search when the semantic API is unavailable
• Action name normalization that strips version prefixes (e.g. bamboohr_1.0.0_bamboohr_create_employee_global →
  bamboohr_create_employee)
• Connector helpers (StackOneTool.connector, Tools.get_connectors()) for connector-aware filtering
• Benchmark suite with 94 evaluation tasks across 8 categories — semantic search achieves 76.6% Hit@5 vs 66.0% for local search (+10.6%
  improvement)

---

Summary by cubic

Adds semantic tool search so users can find and execute actions with natural language. Searches run per-connector on linked accounts, support modes (auto, semantic, local), accept optional project_ids, respect server ranking by default with optional top_k, and fall back to local BM25+TF‑IDF.

• New Features

  • StackOneToolSet.search_tools() and a callable SearchTool (via get_search_tool()); SearchConfig adds default search options and top_k example; Utility Tools removed.
  • SemanticSearchClient with search_action_names(); per‑connector parallel search; respects backend ranking/min_similarity unless top_k is set; supports optional project_ids; normalizes versioned action names; StackOneTool.connector added; StackOneTool now callable.
  • SearchMode supports "auto", "semantic", and "local"; local keyword search moved to local_search.ToolIndex; README updated; new examples (search_tool_example.py, semantic_search_example.py).

• Bug Fixes

  • Scoped searches to available connectors so agents don’t discover tools they can’t execute.
  • Centralized API base URL via DEFAULT_BASE_URL; tests use TEST_BASE_URL; CI skip guards and timeout handling stabilized; Ruff formatting fixes; type-checking fixes.

^{Written for commit 532ac23. Summary will update on new commits.}

[shashi-stackone]

Hey @willleeney Thanks for suggesting above change. After removing the utility_tools abstraction SDK looking so clean. Please have look at the latest changes and let me know if there still chances of improvements ..

As we are planning further refactor I am also thinking to include the following either as pert of this PR or furhter PRS

• Adding tool parameter schema needed for each Agent frameworks (Explain later if needed)
• Adding more conversations in the SDKs to_pydantic, to_adk, to_dspy etc natievly so that conversion become one liner
• Explore more enhancements as we go

[willleeney]

lgtm

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 8 comments.

Comments suppressed due to low confidence (1)

tests/test_local_search.py:92

• The tools_collection fixture at line 90 is no longer used by any test in this file since the TestToolsUtilityTools and TestToolExecute test classes were removed. This unused fixture can be removed to keep the test file clean.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[cubic-dev-ai]

1 issue found across 9 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="tests/conftest.py">

<violation number="1" location="tests/conftest.py:9">
P2: Module-level constant was added before imports, which violates the project's enforced import-order lint rule (E402) and can break CI.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[willleeney]

lgtm