stackone-ai 2.5.0__tar.gz → 2.6.0__tar.gz

stackone_ai-2.6.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "2.6.0"
+}

{stackone_ai-2.5.0 → stackone_ai-2.6.0}/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [2.6.0](https://github.com/StackOneHQ/stackone-ai-python/compare/stackone-ai-v2.5.1...stackone-ai-v2.6.0) (2026-04-07)
+
+
+### Features
+
+* include available connectors in search/execute tool descriptions ([#165](https://github.com/StackOneHQ/stackone-ai-python/issues/165)) ([544f41e](https://github.com/StackOneHQ/stackone-ai-python/commit/544f41ef1340d11f58be1a34e627aa8e81f1102d))
+
+## [2.5.1](https://github.com/StackOneHQ/stackone-ai-python/compare/stackone-ai-v2.5.0...stackone-ai-v2.5.1) (2026-03-26)
+
+
+### Bug Fixes
+
+* **search:** fall back to local search when semantic results don't match MCP tools ([#159](https://github.com/StackOneHQ/stackone-ai-python/issues/159)) ([2c86475](https://github.com/StackOneHQ/stackone-ai-python/commit/2c864759f43dc701d1bfa8407badf4a10f608332))
+
 ## [2.5.0](https://github.com/StackOneHQ/stackone-ai-python/compare/stackone-ai-v2.4.0...stackone-ai-v2.5.0) (2026-03-25)
 
 

{stackone_ai-2.5.0 → stackone_ai-2.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stackone-ai
-Version: 2.5.0
+Version: 2.6.0
 Summary: agents performing actions on your SaaS
 Author-email: StackOne <support@stackone.com>
 License-File: LICENSE

stackone_ai-2.6.0/examples/search_tool_example.py

@@ -0,0 +1,66 @@
+"""Search tool patterns: callable wrapper and config overrides.
+
+For semantic search basics, see semantic_search_example.py.
+For full agent execution, see agent_tool_search.py.
+
+Prerequisites:
+    - STACKONE_API_KEY environment variable
+    - STACKONE_ACCOUNT_ID environment variable
+
+Run with:
+    uv run python examples/search_tool_example.py
+"""
+
+from __future__ import annotations
+
+import os
+
+try:
+    from dotenv import load_dotenv
+
+    load_dotenv()
+except ModuleNotFoundError:
+    pass
+
+from stackone_ai import StackOneToolSet
+
+
+def main() -> None:
+    api_key = os.getenv("STACKONE_API_KEY")
+    account_id = os.getenv("STACKONE_ACCOUNT_ID")
+
+    if not api_key:
+        print("Set STACKONE_API_KEY to run this example.")
+        return
+    if not account_id:
+        print("Set STACKONE_ACCOUNT_ID to run this example.")
+        return
+
+    # --- Example 1: get_search_tool() callable ---
+    print("=== get_search_tool() callable ===\n")
+
+    toolset = StackOneToolSet(api_key=api_key, account_id=account_id, search={})
+    search_tool = toolset.get_search_tool()
+
+    queries = ["cancel an event", "list employees", "send a message"]
+    for query in queries:
+        tools = search_tool(query, top_k=3)
+        names = [t.name for t in tools]
+        print(f'  "{query}" -> {", ".join(names) or "(none)"}')
+
+    # --- Example 2: Constructor top_k vs per-call override ---
+    print("\n=== Constructor top_k vs per-call override ===\n")
+
+    toolset_3 = StackOneToolSet(api_key=api_key, account_id=account_id, search={"top_k": 3})
+
+    query = "manage employee records"
+
+    tools_3 = toolset_3.search_tools(query)
+    print(f"Constructor top_k=3: got {len(tools_3)} tools")
+
+    tools_override = toolset_3.search_tools(query, top_k=10)
+    print(f"Per-call top_k=10 (overrides constructor 3): got {len(tools_override)} tools")
+
+
+if __name__ == "__main__":
+    main()

{stackone_ai-2.5.0 → stackone_ai-2.6.0}/examples/semantic_search_example.py

@@ -133,7 +133,6 @@ def example_search_action_names():
     print(f"Top {len(results_limited)} matches from the full catalog:")
     for r in results_limited:
         print(f"  [{r.similarity_score:.2f}] {r.id}")
-        print(f"         {r.description}")
     print()
 
     # Show filtering effect when account_ids are available

{stackone_ai-2.5.0 → stackone_ai-2.6.0}/examples/test_examples.py

@@ -33,6 +33,7 @@ OPTIONAL_DEPENDENCIES = {
     "search_tool_example.py": ["mcp"],
     "semantic_search_example.py": ["mcp"],
     "mcp_server.py": ["mcp"],
+    "workday_integration.py": ["openai", "mcp"],
 }
 
 

stackone_ai-2.6.0/examples/workday_integration.py

@@ -0,0 +1,91 @@
+"""Workday integration: timeout and account scoping for slow providers.
+
+Workday can take 10-15s to respond. This example shows how to configure
+timeout and account_ids through the execute config.
+
+Prerequisites:
+    - STACKONE_API_KEY environment variable
+    - STACKONE_ACCOUNT_ID environment variable (a Workday-connected account)
+    - OPENAI_API_KEY environment variable
+
+Run with:
+    uv run python examples/workday_integration.py
+"""
+
+from __future__ import annotations
+
+import json
+import os
+
+try:
+    from dotenv import load_dotenv
+
+    load_dotenv()
+except ModuleNotFoundError:
+    pass
+
+from openai import OpenAI
+
+from stackone_ai import StackOneToolSet
+
+
+def main() -> None:
+    api_key = os.getenv("STACKONE_API_KEY")
+    account_id = os.getenv("STACKONE_ACCOUNT_ID")
+
+    if not api_key:
+        print("Set STACKONE_API_KEY to run this example.")
+        return
+    if not account_id:
+        print("Set STACKONE_ACCOUNT_ID to run this example.")
+        return
+
+    # Timeout for slow providers, account_id for scoping
+    toolset = StackOneToolSet(
+        api_key=api_key,
+        account_id=account_id,
+        search={"method": "auto", "top_k": 5},
+        timeout=120,
+    )
+    client = OpenAI()
+
+    def run_agent(messages: list[dict], tools: list[dict], max_steps: int = 10) -> None:
+        """Simple agent loop: call LLM, execute tools, repeat."""
+        for _ in range(max_steps):
+            response = client.chat.completions.create(model="gpt-5.4", messages=messages, tools=tools)
+            choice = response.choices[0]
+
+            if not choice.message.tool_calls:
+                print(f"Answer: {choice.message.content}")
+                return
+
+            messages.append(choice.message.model_dump(exclude_none=True))
+            for tc in choice.message.tool_calls:
+                print(f"  -> {tc.function.name}({tc.function.arguments[:80]})")
+                result = toolset.execute(tc.function.name, tc.function.arguments)
+                messages.append({"role": "tool", "tool_call_id": tc.id, "content": json.dumps(result)})
+
+    # --- Example 1: Search and execute mode ---
+    print("=== Search and execute mode ===\n")
+    run_agent(
+        messages=[
+            {"role": "system", "content": "Use tool_search to find tools, then tool_execute to run them."},
+            {"role": "user", "content": "List the first 5 employees."},
+        ],
+        tools=toolset.openai(mode="search_and_execute"),
+    )
+
+    # --- Example 2: Normal mode ---
+    print("\n=== Normal mode ===\n")
+    tools = toolset.fetch_tools(actions=["workday_*_employee*"])
+    if len(tools) == 0:
+        print("No Workday tools found for this account.")
+    else:
+        run_agent(
+            messages=[{"role": "user", "content": "List the first 5 employees."}],
+            tools=tools.to_openai(),
+        )
+
+
+if __name__ == "__main__":
+    main()

{stackone_ai-2.5.0 → stackone_ai-2.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "stackone-ai"
-version = "2.5.0"
+version = "2.6.0"
 description = "agents performing actions on your SaaS"
 readme = "README.md"
 requires-python = ">=3.10"

{stackone_ai-2.5.0 → stackone_ai-2.6.0}/stackone_ai/__init__.py

@@ -23,4 +23,4 @@ __all__ = [
     "SemanticSearchResponse",
     "SemanticSearchError",
 ]
-__version__ = "2.5.0"
+__version__ = "2.6.0"

{stackone_ai-2.5.0 → stackone_ai-2.6.0}/stackone_ai/models.py

@@ -65,6 +65,7 @@ class ExecuteConfig(BaseModel):
     parameter_locations: dict[str, ParameterLocation] = Field(
         default_factory=dict, description="Maps parameter names to their location in the request"
     )
+    timeout: float = Field(default=60.0, description="Request timeout in seconds")
 
 
 class ToolParameters(BaseModel):
@@ -249,7 +250,7 @@ class StackOneTool(BaseModel):
             if query_params:
                 request_kwargs["params"] = query_params
 
-            response = httpx.request(**request_kwargs)
+            response = httpx.request(**request_kwargs, timeout=self._execute_config.timeout)
             response_status = response.status_code
             response.raise_for_status()
 

{stackone_ai-2.5.0 → stackone_ai-2.6.0}/stackone_ai/toolset.py

@@ -59,7 +59,7 @@ class SearchConfig(TypedDict, total=False):
 class ExecuteToolsConfig(TypedDict, total=False):
     """Execution configuration for the StackOneToolSet constructor.
 
-    Controls default account scoping for tool execution.
+    Controls default account scoping and timeout for tool execution.
 
     When set to ``None`` (default), no account scoping is applied.
     When provided, ``account_ids`` flow through to ``openai(mode="search_and_execute")``
@@ -69,6 +69,10 @@ class ExecuteToolsConfig(TypedDict, total=False):
     account_ids: list[str]
     """Account IDs to scope tool discovery and execution."""
 
+    timeout: float
+    """Request timeout in seconds. Default: 60. Can also be set as a top-level
+    constructor param which takes precedence."""
+
 
 _SEARCH_DEFAULT: SearchConfig = {"method": "auto"}
 
@@ -205,13 +209,14 @@ class _ExecuteTool(StackOneTool):
             return {"error": f"Invalid input: {exc}", "tool_name": tool_name}
 
 
-def _create_search_tool(api_key: str) -> _SearchTool:
+def _create_search_tool(api_key: str, connectors: str = "") -> _SearchTool:
     name = "tool_search"
+    connector_line = f" Available connectors: {connectors}." if connectors else ""
     description = (
         "Search for available tools by describing what you need. "
         "Returns matching tool names, descriptions, and parameter schemas. "
         "Use the returned parameter schemas to know exactly what to pass "
-        "when calling tool_execute."
+        f"when calling tool_execute.{connector_line}"
     )
     parameters = ToolParameters(
         type="object",
@@ -259,14 +264,14 @@ def _create_search_tool(api_key: str) -> _SearchTool:
     return tool
 
 
-def _create_execute_tool(api_key: str) -> _ExecuteTool:
+def _create_execute_tool(api_key: str, connectors: str = "") -> _ExecuteTool:
     name = "tool_execute"
+    connector_line = f" Available connectors: {connectors}." if connectors else ""
     description = (
         "Execute a tool by name with the given parameters. "
         "Use tool_search first to find available tools. "
         "The parameters field must match the parameter schema returned "
-        "by tool_search. Pass parameters as a nested object matching "
-        "the schema structure."
+        f"by tool_search. Pass parameters as a nested object matching the schema structure.{connector_line}"
     )
     parameters = ToolParameters(
         type="object",
@@ -415,6 +420,7 @@ class _StackOneRpcTool(StackOneTool):
         api_key: str,
         base_url: str,
         account_id: str | None,
+        timeout: float = 60.0,
     ) -> None:
         execute_config = ExecuteConfig(
             method="POST",
@@ -423,6 +429,7 @@ class _StackOneRpcTool(StackOneTool):
             headers={},
             body_type="json",
             parameter_locations=dict(_RPC_PARAMETER_LOCATIONS),
+            timeout=timeout,
         )
         super().__init__(
             description=description,
@@ -555,6 +562,7 @@ class StackOneToolSet:
         base_url: str | None = None,
         search: SearchConfig | None = None,
         execute: ExecuteToolsConfig | None = None,
+        timeout: float | None = None,
     ) -> None:
         """Initialize StackOne tools with authentication
 
@@ -570,7 +578,10 @@ class StackOneToolSet:
                 Per-call options always override these defaults.
             execute: Execution configuration. Controls default account scoping
                 for tool execution. Pass ``{"account_ids": ["acc-1"]}`` to scope
-                meta tools to specific accounts.
+                tools to specific accounts.
+            timeout: Request timeout in seconds for tool execution HTTP calls.
+                Default: 60. Takes precedence over ``execute.timeout`` if set.
+                Increase for slow providers (e.g. Workday).
 
         Raises:
             ToolsetConfigError: If no API key is provided or found in environment
@@ -584,10 +595,12 @@ class StackOneToolSet:
         self.api_key: str = api_key_value
         self.account_id = account_id
         self.base_url = base_url or DEFAULT_BASE_URL
-        self._account_ids: list[str] = []
+        self._account_ids: list[str] = execute.get("account_ids", []) if execute else []
         self._semantic_client: SemanticSearchClient | None = None
         self._search_config: SearchConfig | None = search
         self._execute_config: ExecuteToolsConfig | None = execute
+        execute_timeout = execute.get("timeout") if execute else None
+        self._timeout: float = timeout if timeout is not None else (execute_timeout or 60.0)
         self._tools_cache: Tools | None = None
 
     def set_accounts(self, account_ids: list[str]) -> StackOneToolSet:
@@ -645,10 +658,20 @@ class StackOneToolSet:
         if account_ids:
             self._account_ids = account_ids
 
-        search_tool = _create_search_tool(self.api_key)
+        # Discover available connectors for dynamic descriptions
+        connectors_str = ""
+        try:
+            all_tools = self.fetch_tools(account_ids=self._account_ids)
+            connectors = sorted(all_tools.get_connectors())
+            if connectors:
+                connectors_str = ", ".join(connectors)
+        except Exception:
+            logger.debug("Could not discover connectors for tool descriptions")
+
+        search_tool = _create_search_tool(self.api_key, connectors=connectors_str)
         search_tool._toolset = self
 
-        execute_tool = _create_execute_tool(self.api_key)
+        execute_tool = _create_execute_tool(self.api_key, connectors=connectors_str)
         execute_tool._toolset = self
 
         return Tools([search_tool, execute_tool])
@@ -933,6 +956,21 @@ class StackOneToolSet:
             matched_tools = [t for t in all_tools if t.name in seen_names]
             matched_tools.sort(key=lambda t: action_order.get(t.name, float("inf")))
 
+            # Auto mode: if semantic returned results but none matched MCP tools, fall back to local
+            if effective_search == "auto" and len(matched_tools) == 0:
+                logger.warning(
+                    "Semantic search returned %d results but none matched MCP tools, "
+                    "falling back to local search",
+                    len(all_results),
+                )
+                return self._local_search(
+                    query,
+                    all_tools,
+                    connector=connector,
+                    top_k=effective_top_k,
+                    min_similarity=effective_min_sim,
+                )
+
             return Tools(matched_tools)
 
         except SemanticSearchError as e:
@@ -1177,6 +1215,7 @@ class StackOneToolSet:
             api_key=self.api_key,
             base_url=self.base_url,
             account_id=account_id,
+            timeout=self._timeout,
         )
 
     def _normalize_schema_properties(self, schema: dict[str, Any]) -> dict[str, Any]:

{stackone_ai-2.5.0 → stackone_ai-2.6.0}/tests/test_semantic_search.py

@@ -959,3 +959,81 @@ class TestSemanticSearchDeduplication:
         assert results[0].id == "breathehr_1.0.0_breathehr_list_employees_global"
         # Sorted by score descending
         assert results[0].similarity_score == 0.95
+
+
+class TestZeroMatchFallback:
+    """Tests for fallback when semantic results don't match MCP tools."""
+
+    @patch.object(SemanticSearchClient, "search")
+    @patch("stackone_ai.toolset._fetch_mcp_tools")
+    def test_auto_mode_falls_back_when_no_tools_match(
+        self,
+        mock_fetch: MagicMock,
+        mock_search: MagicMock,
+    ) -> None:
+        """Auto mode falls back to local search when semantic results don't match any MCP tools."""
+        from stackone_ai import StackOneToolSet
+        from stackone_ai.toolset import _McpToolDefinition
+
+        # Semantic returns results with IDs that won't match MCP tool names
+        mock_search.return_value = SemanticSearchResponse(
+            results=[
+                SemanticSearchResult(
+                    id="unknown_1.0.0_nonexistent_action_global",
+                    similarity_score=0.95,
+                ),
+            ],
+            total_count=1,
+            query="manage employees",
+        )
+
+        mock_fetch.return_value = [
+            _McpToolDefinition(
+                name="bamboohr_create_employee",
+                description="Creates a new employee in BambooHR",
+                input_schema={"type": "object", "properties": {}},
+            ),
+        ]
+
+        toolset = StackOneToolSet(api_key="test-key", search={"method": "auto"})
+        tools = toolset.search_tools("manage employees", top_k=5)
+
+        # Should fall back to local search and return results (not empty)
+        assert len(tools) > 0
+
+    @patch.object(SemanticSearchClient, "search")
+    @patch("stackone_ai.toolset._fetch_mcp_tools")
+    def test_semantic_mode_does_not_fall_back(
+        self,
+        mock_fetch: MagicMock,
+        mock_search: MagicMock,
+    ) -> None:
+        """Semantic mode returns empty results when no tools match, does not fall back."""
+        from stackone_ai import StackOneToolSet
+        from stackone_ai.toolset import _McpToolDefinition
+
+        # Semantic returns results with IDs that won't match MCP tool names
+        mock_search.return_value = SemanticSearchResponse(
+            results=[
+                SemanticSearchResult(
+                    id="unknown_1.0.0_nonexistent_action_global",
+                    similarity_score=0.95,
+                ),
+            ],
+            total_count=1,
+            query="manage employees",
+        )
+
+        mock_fetch.return_value = [
+            _McpToolDefinition(
+                name="bamboohr_create_employee",
+                description="Creates a new employee in BambooHR",
+                input_schema={"type": "object", "properties": {}},
+            ),
+        ]
+
+        toolset = StackOneToolSet(api_key="test-key", search={"method": "auto"})
+        tools = toolset.search_tools("manage employees", search="semantic", top_k=5)
+
+        # Semantic mode should return empty, not fall back
+        assert len(tools) == 0

{stackone_ai-2.5.0 → stackone_ai-2.6.0}/uv.lock

@@ -3972,7 +3972,7 @@ wheels = [
 
 [[package]]
 name = "stackone-ai"
-version = "2.5.0"
+version = "2.6.0"
 source = { editable = "." }
 dependencies = [
     { name = "bm25s" },

stackone_ai-2.5.0/.release-please-manifest.json

@@ -1,3 +0,0 @@
-{
-  ".": "2.5.0"
-}