Skip to content

fix(search): make ToolsetConfigError actionable and fix misleading docs #188

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
CameronCarlin merged 2 commits into from
May 22, 2026
Merged

fix(search): make ToolsetConfigError actionable and fix misleading docs #188

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1f323ae
fix(search): make ToolsetConfigError actionable and fix misleading docs
CameronCarlin May 22, 2026
1b7a8c6
fix(search): align error reference and fix Basic Usage snippet
CameronCarlin May 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 12 additions & 7 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -228,7 +228,10 @@ For the full catalog (or the meta search/execute tools), use the `.pydantic_ai()
```python
toolset = StackOneToolSet()
tools = toolset.pydantic_ai(account_ids=[os.environ["STACKONE_ACCOUNT_ID"]])
# or pydantic_ai(mode="search_and_execute") for agent-driven discovery

# For agent-driven discovery, enable search on the constructor:
# toolset = StackOneToolSet(search={"method": "auto"})
# tools = toolset.pydantic_ai(mode="search_and_execute")
```

</details>
Expand Down Expand Up @@ -359,15 +362,15 @@ Search for tools using natural language queries. Works with both semantic (cloud

```python
import os
from stackone_ai import StackOneToolSet

# Get a callable search tool
toolset = StackOneToolSet()
# Get a callable search tool — search must be enabled on the toolset
toolset = StackOneToolSet(search={"method": "auto"})
account_id = os.getenv("STACKONE_ACCOUNT_ID")
all_tools = toolset.fetch_tools(account_ids=[account_id])
search_tool = toolset.get_search_tool()
Comment thread
CameronCarlin marked this conversation as resolved.

# Search for relevant tools — returns a Tools collection
tools = search_tool("manage employees", top_k=5)
# Search for relevant tools — returns a Tools collection scoped to the account
tools = search_tool("manage employees", top_k=5, account_ids=[account_id])

# Execute a discovered tool directly
tools[0](limit=10)
Expand All @@ -381,7 +384,9 @@ Discover tools using natural language instead of exact names. Queries like "onbo
import os
from stackone_ai import StackOneToolSet

toolset = StackOneToolSet()
# Search must be enabled on the constructor — pass `search={}` for defaults,
# or set a backend / top_k explicitly.
toolset = StackOneToolSet(search={"method": "auto"})

# Search by intent — returns Tools collection ready for any framework
account_id = os.getenv("STACKONE_ACCOUNT_ID")
Expand Down
21 changes: 13 additions & 8 deletions stackone_ai/toolset.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -645,13 +645,14 @@ def get_search_tool(self, *, search: SearchMode | None = None) -> SearchTool:

Example::

toolset = StackOneToolSet()
toolset = StackOneToolSet(search={"method": "auto"})
search_tool = toolset.get_search_tool()
tools = search_tool("manage employee records", account_ids=["acc-123"])
"""
if self._search_config is None:
raise ToolsetConfigError(
"Search is disabled. Initialize StackOneToolSet with a search config to enable."
"Search is disabled. Pass search={} (or search={'method': 'auto'}) to "
"StackOneToolSet(...) to enable. See README 'Search Tool' for options."
)
Comment thread
CameronCarlin marked this conversation as resolved.

config: SearchConfig = {**self._search_config}
Expand All @@ -664,7 +665,8 @@ def _build_tools(self, account_ids: list[str] | None = None) -> Tools:
"""Build tool_search + tool_execute tools scoped to this toolset."""
if self._search_config is None:
raise ToolsetConfigError(
"Search is disabled. Initialize StackOneToolSet with a search config to enable."
"Search is disabled. Pass search={} (or search={'method': 'auto'}) to "
"StackOneToolSet(...) to enable. See README 'Search Tool' for options."
)

if account_ids:
Expand Down Expand Up @@ -713,8 +715,8 @@ def openai(
toolset = StackOneToolSet()
tools = toolset.openai()

# Meta tools for agent-driven discovery
toolset = StackOneToolSet()
# Meta tools for agent-driven discovery — search must be enabled
toolset = StackOneToolSet(search={"method": "auto"})
tools = toolset.openai(mode="search_and_execute")
"""
effective_account_ids = account_ids or (
Expand Down Expand Up @@ -783,7 +785,8 @@ def pydantic_ai(
tools = toolset.pydantic_ai()
agent = Agent("openai:gpt-5.4", tools=tools)

# Meta tools for agent-driven discovery
# Meta tools for agent-driven discovery — search must be enabled
toolset = StackOneToolSet(search={"method": "auto"})
tools = toolset.pydantic_ai(mode="search_and_execute")
"""
effective_account_ids = account_ids or (
Expand Down Expand Up @@ -929,7 +932,8 @@ def search_tools(
"""
if self._search_config is None:
raise ToolsetConfigError(
"Search is disabled. Initialize StackOneToolSet with a search config to enable."
"Search is disabled. Pass search={} (or search={'method': 'auto'}) to "
"StackOneToolSet(...) to enable. See README 'Search Tool' for options."
)

# Merge constructor defaults with per-call overrides
Expand Down Expand Up @@ -1082,7 +1086,8 @@ def search_action_names(
"""
if self._search_config is None:
raise ToolsetConfigError(
"Search is disabled. Initialize StackOneToolSet with search config to enable."
"Search is disabled. Pass search={} (or search={'method': 'auto'}) to "
"StackOneToolSet(...) to enable. See README 'Search Tool' for options."
)

# Merge constructor defaults with per-call overrides
Expand Down