stackone-ai 2.4.0__tar.gz → 2.5.1__tar.gz

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

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

{stackone_ai-2.4.0 → stackone_ai-2.5.1}/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [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)
+
+
+### Features
+
+* **search-tools:** LLM-driven search and execute and new API ([#151](https://github.com/StackOneHQ/stackone-ai-python/issues/151)) ([a5e5723](https://github.com/StackOneHQ/stackone-ai-python/commit/a5e5723689d702ce4d176194a0d6a43486bcdff7))
+
 ## [2.4.0](https://github.com/StackOneHQ/stackone-ai-python/compare/stackone-ai-v2.3.1...stackone-ai-v2.4.0) (2026-03-06)
 
 

{stackone_ai-2.4.0 → stackone_ai-2.5.1}/PKG-INFO

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

stackone_ai-2.5.1/examples/agent_tool_search.py

@@ -0,0 +1,202 @@
+"""Search and execute example: LLM-driven tool discovery and execution.
+
+There are two ways to give tools to an LLM:
+
+1. ``toolset.openai()`` — fetches ALL tools and converts them to OpenAI format.
+   Token cost scales with the number of tools in your catalog.
+
+2. ``toolset.openai(mode="search_and_execute")`` — returns just 2 tools
+   (tool_search + tool_execute). The LLM discovers and runs tools on-demand,
+   keeping token usage constant regardless of catalog size.
+
+This example demonstrates approach 2 with two patterns:
+- Raw client (OpenAI): manual agent loop with ``toolset.execute()``
+- LangChain: framework handles tool execution automatically
+
+Prerequisites:
+    - STACKONE_API_KEY environment variable
+    - STACKONE_ACCOUNT_ID environment variable
+    - OPENAI_API_KEY environment variable
+
+Run with:
+    uv run python examples/agent_tool_search.py
+"""
+
+from __future__ import annotations
+
+import json
+import os
+
+try:
+    from dotenv import load_dotenv
+
+    load_dotenv()
+except ModuleNotFoundError:
+    pass
+
+from stackone_ai import StackOneToolSet
+
+
+def example_openai() -> None:
+    """Raw client: OpenAI.
+
+    Shows: init toolset -> get OpenAI tools -> manual agent loop with toolset.execute().
+    """
+    print("=" * 60)
+    print("Example 1: Raw client (OpenAI) — manual execution")
+    print("=" * 60)
+    print()
+
+    try:
+        from openai import OpenAI
+    except ImportError:
+        print("Skipped: pip install openai")
+        print()
+        return
+
+    if not os.getenv("OPENAI_API_KEY"):
+        print("Skipped: Set OPENAI_API_KEY to run this example.")
+        print()
+        return
+
+    # 1. Init toolset
+    account_id = os.getenv("STACKONE_ACCOUNT_ID")
+    toolset = StackOneToolSet(
+        account_id=account_id,
+        search={"method": "semantic", "top_k": 3},
+        execute={"account_ids": [account_id]} if account_id else None,
+    )
+
+    # 2. Get tools in OpenAI format
+    openai_tools = toolset.openai(mode="search_and_execute")
+
+    # 3. Create OpenAI client and run agent loop
+    client = OpenAI()
+    messages: list[dict] = [
+        {
+            "role": "system",
+            "content": (
+                "You are a helpful scheduling assistant. Use tool_search to find relevant tools, "
+                "then tool_execute to run them. Always read the parameter schemas from tool_search "
+                "results carefully. If a tool needs a user URI, first search for and call a "
+                '"get current user" tool to obtain it. If a tool execution fails, try different '
+                "parameters or a different tool."
+            ),
+        },
+        {"role": "user", "content": "List my upcoming Calendly events for the next week."},
+    ]
+
+    for _step in range(10):
+        response = client.chat.completions.create(
+            model="gpt-5.4",
+            messages=messages,
+            tools=openai_tools,
+            tool_choice="auto",
+        )
+
+        choice = response.choices[0]
+
+        # 4. If no tool calls, print final answer and stop
+        if not choice.message.tool_calls:
+            print(f"Answer: {choice.message.content}")
+            break
+
+        # 5. Execute tool calls manually and feed results back
+        messages.append(choice.message.model_dump(exclude_none=True))
+        for tool_call in choice.message.tool_calls:
+            print(f"  -> {tool_call.function.name}({tool_call.function.arguments})")
+            result = toolset.execute(tool_call.function.name, tool_call.function.arguments)
+            messages.append(
+                {
+                    "role": "tool",
+                    "tool_call_id": tool_call.id,
+                    "content": json.dumps(result),
+                }
+            )
+
+    print()
+
+
+def example_langchain() -> None:
+    """Framework: LangChain with auto-execution.
+
+    Shows: init toolset -> get LangChain tools -> bind to model -> framework executes tools.
+    No toolset.execute() needed — the framework calls _run() on tools automatically.
+    """
+    print("=" * 60)
+    print("Example 2: LangChain — framework handles execution")
+    print("=" * 60)
+    print()
+
+    try:
+        from langchain_core.messages import AIMessage, HumanMessage, SystemMessage, ToolMessage
+        from langchain_openai import ChatOpenAI
+    except ImportError:
+        print("Skipped: pip install langchain-openai")
+        print()
+        return
+
+    if not os.getenv("OPENAI_API_KEY"):
+        print("Skipped: Set OPENAI_API_KEY to run this example.")
+        print()
+        return
+
+    # 1. Init toolset
+    account_id = os.getenv("STACKONE_ACCOUNT_ID")
+    toolset = StackOneToolSet(
+        account_id=account_id,
+        search={"method": "semantic", "top_k": 3},
+        execute={"account_ids": [account_id]} if account_id else None,
+    )
+
+    # 2. Get tools in LangChain format and bind to model
+    langchain_tools = toolset.langchain(mode="search_and_execute")
+    tools_by_name = {tool.name: tool for tool in langchain_tools}
+    model = ChatOpenAI(model="gpt-5.4").bind_tools(langchain_tools)
+
+    # 3. Run agent loop
+    messages = [
+        SystemMessage(
+            content=(
+                "You are a helpful scheduling assistant. Use tool_search to find relevant tools, "
+                "then tool_execute to run them. Always read the parameter schemas from tool_search "
+                "results carefully. If a tool needs a user URI, first search for and call a "
+                '"get current user" tool to obtain it. If a tool execution fails, try different '
+                "parameters or a different tool."
+            ),
+        ),
+        HumanMessage(content="List my upcoming Calendly events for the next week."),
+    ]
+
+    for _step in range(10):
+        response: AIMessage = model.invoke(messages)
+
+        # 4. If no tool calls, print final answer and stop
+        if not response.tool_calls:
+            print(f"Answer: {response.content}")
+            break
+
+        # 5. Framework-compatible execution — invoke LangChain tools directly
+        messages.append(response)
+        for tool_call in response.tool_calls:
+            print(f"  -> {tool_call['name']}({json.dumps(tool_call['args'])})")
+            tool = tools_by_name[tool_call["name"]]
+            result = tool.invoke(tool_call["args"])
+            messages.append(ToolMessage(content=json.dumps(result), tool_call_id=tool_call["id"]))
+
+    print()
+
+
+def main() -> None:
+    """Run all examples."""
+    api_key = os.getenv("STACKONE_API_KEY")
+    if not api_key:
+        print("Set STACKONE_API_KEY to run these examples.")
+        return
+
+    example_openai()
+    example_langchain()
+
+
+if __name__ == "__main__":
+    main()

{stackone_ai-2.4.0 → stackone_ai-2.5.1}/examples/crewai_integration.py

@@ -34,7 +34,7 @@ def crewai_integration():
         goal=f"What is the employee with the id {employee_id}?",
         backstory="With over 10 years of experience in HR and employee management, "
         "you excel at finding patterns in complex datasets.",
-        llm="gpt-4o-mini",
+        llm="gpt-5.4",
         tools=langchain_tools,
         max_iter=2,
     )

{stackone_ai-2.4.0 → stackone_ai-2.5.1}/examples/langchain_integration.py

@@ -33,7 +33,7 @@ def langchain_integration() -> None:
         assert hasattr(tool, "args_schema"), "Expected tool to have args_schema"
 
     # Create model with tools
-    model = ChatOpenAI(model="gpt-4o-mini")
+    model = ChatOpenAI(model="gpt-5.4")
     model_with_tools = model.bind_tools(langchain_tools)
 
     result = model_with_tools.invoke(f"Can you get me information about employee with ID: {employee_id}?")

{stackone_ai-2.4.0 → stackone_ai-2.5.1}/examples/openai_integration.py

@@ -53,7 +53,7 @@ def openai_integration() -> None:
     ]
 
     response = client.chat.completions.create(
-        model="gpt-4o-mini",
+        model="gpt-5.4",
         messages=messages,
         tools=openai_tools,
         tool_choice="auto",
@@ -81,7 +81,7 @@ def openai_integration() -> None:
 
     # Verify the final response
     final_response = client.chat.completions.create(
-        model="gpt-4o-mini",
+        model="gpt-5.4",
         messages=messages,
         tools=openai_tools,
         tool_choice="auto",

{stackone_ai-2.4.0 → stackone_ai-2.5.1}/examples/search_tool_example.py

@@ -198,7 +198,7 @@ def example_with_openai():
 
         # Create a chat completion with discovered tools
         response = client.chat.completions.create(
-            model="gpt-4",
+            model="gpt-5.4",
             messages=[
                 {
                     "role": "system",
@@ -246,7 +246,7 @@ def example_with_langchain():
             print(f"  - {tool.name}: {tool.description}")
 
         # Create LangChain agent
-        llm = ChatOpenAI(model="gpt-4", temperature=0)
+        llm = ChatOpenAI(model="gpt-5.4", temperature=0)
 
         prompt = ChatPromptTemplate.from_messages(
             [

{stackone_ai-2.4.0 → stackone_ai-2.5.1}/examples/semantic_search_example.py

@@ -132,7 +132,7 @@ def example_search_action_names():
     # Show the limited results
     print(f"Top {len(results_limited)} matches from the full catalog:")
     for r in results_limited:
-        print(f"  [{r.similarity_score:.2f}] {r.action_name} ({r.connector_key})")
+        print(f"  [{r.similarity_score:.2f}] {r.id}")
         print(f"         {r.description}")
     print()
 
@@ -143,7 +143,7 @@ def example_search_action_names():
         filtered = toolset.search_action_names(query, account_ids=_account_ids, top_k=5)
         print(f"  Filtered to {len(filtered)} matches (only your connectors):")
         for r in filtered:
-            print(f"    [{r.similarity_score:.2f}] {r.action_name} ({r.connector_key})")
+            print(f"    [{r.similarity_score:.2f}] {r.id}")
     else:
         print("Tip: Set STACKONE_ACCOUNT_ID to see results filtered to your linked connectors.")
 
@@ -197,7 +197,7 @@ def example_search_tools_with_connector():
     print("=" * 60)
     print()
 
-    toolset = StackOneToolSet()
+    toolset = StackOneToolSet(search={})
 
     query = "book a meeting"
     connector = "calendly"
@@ -230,7 +230,7 @@ def example_search_tool_agent_loop():
     print("=" * 60)
     print()
 
-    toolset = StackOneToolSet()
+    toolset = StackOneToolSet(search={})
 
     print("Step 1: Fetching tools from your linked accounts via MCP...")
     all_tools = toolset.fetch_tools(account_ids=_account_ids)
@@ -281,7 +281,7 @@ def example_openai_agent_loop():
 
     if openai_key:
         client = OpenAI()
-        model = "gpt-4o-mini"
+        model = "gpt-5.4"
         provider = "OpenAI"
     elif google_key:
         client = OpenAI(
@@ -298,7 +298,7 @@ def example_openai_agent_loop():
     print(f"Using {provider} ({model})")
     print()
 
-    toolset = StackOneToolSet()
+    toolset = StackOneToolSet(search={})
 
     query = "list upcoming events"
     print(f'Step 1: Discovering tools for "{query}" via semantic search...')
@@ -358,7 +358,7 @@ def example_langchain_semantic():
         print()
         return
 
-    toolset = StackOneToolSet()
+    toolset = StackOneToolSet(search={})
 
     query = "remove a user from the team"
     print(f'Step 1: Searching for "{query}" via semantic search...')

{stackone_ai-2.4.0 → stackone_ai-2.5.1}/pyproject.toml

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

{stackone_ai-2.4.0 → stackone_ai-2.5.1}/stackone_ai/__init__.py

@@ -7,12 +7,13 @@ from stackone_ai.semantic_search import (
     SemanticSearchResponse,
     SemanticSearchResult,
 )
-from stackone_ai.toolset import SearchConfig, SearchMode, SearchTool, StackOneToolSet
+from stackone_ai.toolset import ExecuteToolsConfig, SearchConfig, SearchMode, SearchTool, StackOneToolSet
 
 __all__ = [
     "StackOneToolSet",
     "StackOneTool",
     "Tools",
+    "ExecuteToolsConfig",
     "SearchConfig",
     "SearchMode",
     "SearchTool",
@@ -22,4 +23,4 @@ __all__ = [
     "SemanticSearchResponse",
     "SemanticSearchError",
 ]
-__version__ = "2.4.0"
+__version__ = "2.5.1"

{stackone_ai-2.4.0 → stackone_ai-2.5.1}/stackone_ai/models.py

@@ -414,21 +414,33 @@ class StackOneTool(BaseModel):
 
         for name, details in self.parameters.properties.items():
             python_type: type = str  # Default to str
+            is_nullable = False
             if isinstance(details, dict):
                 type_str = details.get("type", "string")
+                is_nullable = details.get("nullable", False)
                 if type_str == "number":
                     python_type = float
                 elif type_str == "integer":
                     python_type = int
                 elif type_str == "boolean":
                     python_type = bool
+                elif type_str == "object":
+                    python_type = dict
+                elif type_str == "array":
+                    python_type = list
 
-                field = Field(description=details.get("description", ""))
+                if is_nullable:
+                    field = Field(default=None, description=details.get("description", ""))
+                else:
+                    field = Field(description=details.get("description", ""))
             else:
                 field = Field(description="")
 
             schema_props[name] = field
-            annotations[name] = python_type
+            if is_nullable:
+                annotations[name] = python_type | None
+            else:
+                annotations[name] = python_type
 
         # Create the schema class with proper annotations
         schema_class = type(

{stackone_ai-2.4.0 → stackone_ai-2.5.1}/stackone_ai/semantic_search.py

@@ -12,18 +12,15 @@ Each path trades off between speed, filtering, and completeness.
 This is the primary method used when integrating with OpenAI, LangChain, or CrewAI.
 The internal flow is:
 
-1. Fetch ALL tools from linked accounts via MCP (uses account_ids to scope the request)
-2. Extract available connectors from the fetched tools (e.g. {bamboohr, hibob})
-3. Search EACH connector in parallel via the semantic search API (/actions/search)
-4. Collect results, sort by relevance score, apply top_k if specified
-5. Match semantic results back to the fetched tool definitions
-6. Return Tools sorted by relevance score
+1. Fetch tools from linked accounts via MCP (provides connectors and tool schemas)
+2. Search EACH connector in parallel via the semantic search API (/actions/search)
+3. Match search results to MCP tool definitions
+4. Deduplicate, sort by relevance score, apply top_k
+5. Return Tools sorted by relevance score
 
 Key point: only the user's own connectors are searched — no wasted results
-from connectors the user doesn't have. Tools are fetched first, semantic
-search runs second, and only tools that exist in the user's linked
-accounts AND match the semantic query are returned. This prevents
-suggesting tools the user cannot execute.
+from connectors the user doesn't have. Tool schemas come from MCP (source
+of truth), while the search API provides relevance ranking.
 
 If the semantic API is unavailable, the SDK falls back to a local
 BM25 + TF-IDF hybrid search over the fetched tools (unless
@@ -33,10 +30,9 @@ BM25 + TF-IDF hybrid search over the fetched tools (unless
 2. ``search_action_names(query)`` — Lightweight discovery
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Queries the semantic API directly and returns action name metadata
-(name, connector, score, description) **without** fetching full tool
-definitions. This is useful for previewing results before committing
-to a full fetch.
+Queries the semantic API directly and returns action IDs with
+similarity scores, **without** building full tool objects. Useful
+for previewing results before committing to a full fetch.
 
 When ``account_ids`` are provided, each connector is searched in
 parallel (same as ``search_tools``). Without ``account_ids``, results
@@ -71,12 +67,8 @@ class SemanticSearchError(Exception):
 class SemanticSearchResult(BaseModel):
     """Single result from semantic search API."""
 
-    action_name: str
-    connector_key: str
+    id: str
     similarity_score: float
-    label: str
-    description: str
-    project_id: str = "global"
 
 
 class SemanticSearchResponse(BaseModel):
@@ -99,7 +91,7 @@ class SemanticSearchClient:
         client = SemanticSearchClient(api_key="sk-xxx")
         response = client.search("create employee", connector="bamboohr", top_k=5)
         for result in response.results:
-            print(f"{result.action_name}: {result.similarity_score:.2f}")
+            print(f"{result.action_id}: {result.similarity_score:.2f}")
     """
 
     def __init__(
@@ -152,7 +144,7 @@ class SemanticSearchClient:
         Example:
             response = client.search("onboard a new team member", top_k=5)
             for result in response.results:
-                print(f"{result.action_name}: {result.similarity_score:.2f}")
+                print(f"{result.action_id}: {result.similarity_score:.2f}")
         """
         url = f"{self.base_url}/actions/search"
         headers = {
@@ -210,4 +202,4 @@ class SemanticSearchClient:
             )
         """
         response = self.search(query, connector, top_k, project_id, min_similarity=min_similarity)
-        return [r.action_name for r in response.results]
+        return [r.id for r in response.results]