Respect the backend results unless top_k specified explicitly, add python only crewAI example

Author: Shashikant86

examples/crewai_integration.py

@@ -1,6 +1,9 @@
 """
 This example demonstrates how to use StackOne tools with CrewAI.
 
+Note: This example is Python only. CrewAI does not have an official
+TypeScript/Node.js library.
+
 CrewAI uses LangChain tools natively.
 
 ```bash

examples/crewai_semantic_search.py

@@ -0,0 +1,94 @@
+"""
+CrewAI meeting booking agent powered by semantic search.
+
+Note: This example is Python only. CrewAI does not have an official
+TypeScript/Node.js library.
+
+Instead of hardcoding tool names, this example uses semantic search to discover
+scheduling tools (e.g., Calendly) from natural language queries like "book a
+meeting" or "check availability".
+
+Prerequisites:
+- STACKONE_API_KEY environment variable set
+- STACKONE_ACCOUNT_ID environment variable set (Calendly-linked account)
+- OPENAI_API_KEY environment variable set (for CrewAI's LLM)
+
+```bash
+uv run examples/crewai_semantic_search.py
+```
+"""
+
+import os
+
+from crewai import Agent, Crew, Task
+from dotenv import load_dotenv
+
+from stackone_ai import StackOneToolSet
+
+load_dotenv()
+
+_account_ids = [aid.strip() for aid in os.getenv("STACKONE_ACCOUNT_ID", "").split(",") if aid.strip()]
+
+
+def crewai_semantic_search() -> None:
+    toolset = StackOneToolSet()
+
+    # Step 1: Preview — lightweight search returning action names and scores
+    #   search_action_names() queries the semantic API without fetching full
+    #   tool definitions. Useful for inspecting what's available before committing.
+    preview = toolset.search_action_names(
+        "book a meeting or check availability",
+        account_ids=_account_ids
+    )
+    print("Semantic search preview (action names only):")
+    for r in preview:
+        print(f"  [{r.similarity_score:.2f}] {r.action_name} ({r.connector_key})")
+    print()
+
+    # Step 2: Full discovery — fetch matching tools ready for framework use
+    #   search_tools() fetches tools from linked accounts, runs semantic search,
+    #   and returns only tools the user has access to.
+    tools = toolset.search_tools(
+        "schedule meetings, check availability, list events",
+        connector="calendly",
+        account_ids=_account_ids
+    )
+    assert len(tools) > 0, "Expected at least one scheduling tool"
+
+    print(f"Discovered {len(tools)} scheduling tools:")
+    for tool in tools:
+        print(f"  - {tool.name}: {tool.description[:80]}...")
+    print()
+
+    # Step 3: Convert to CrewAI format
+    crewai_tools = tools.to_crewai()
+
+    # Step 4: Create a CrewAI meeting booking agent
+    agent = Agent(
+        role="Meeting Booking Agent",
+        goal="Help users manage their calendar by discovering and booking meetings, "
+        "checking availability, and listing upcoming events.",
+        backstory="You are an AI assistant specialized in calendar management. "
+        "You have access to scheduling tools discovered via semantic search "
+        "and can help users with all meeting-related tasks.",
+        llm="gpt-4o-mini",
+        tools=crewai_tools,
+        max_iter=2,
+        verbose=True,
+    )
+
+    task = Task(
+        description="List upcoming scheduled events to give an overview of the calendar.",
+        agent=agent,
+        expected_output="A summary of upcoming events or a confirmation that events were retrieved.",
+    )
+
+    crew = Crew(agents=[agent], tasks=[task])
+
+    result = crew.kickoff()
+    assert result is not None, "Expected result to be returned"
+    print(f"\nCrew result: {result}")
+
+
+if __name__ == "__main__":
+    crewai_semantic_search()

stackone_ai/models.py

@@ -450,6 +450,64 @@ def _run(self, **kwargs: Any) -> Any:
 
         return StackOneLangChainTool()
 
+    def to_crewai(self) -> Any:
+        """Convert this tool to CrewAI format
+
+        Requires the ``crewai`` package (``pip install crewai``).
+
+        Returns:
+            Tool as a ``crewai.tools.BaseTool`` instance
+        """
+        try:
+            from crewai.tools.base_tool import BaseTool as CrewAIBaseTool
+        except ImportError as e:
+            raise ImportError("crewai is required for to_crewai(). Install with: pip install crewai") from e
+
+        schema_props: dict[str, Any] = {}
+        annotations: dict[str, Any] = {}
+
+        for name, details in self.parameters.properties.items():
+            python_type: type = str
+            if isinstance(details, dict):
+                type_str = details.get("type", "string")
+                if type_str == "number":
+                    python_type = float
+                elif type_str == "integer":
+                    python_type = int
+                elif type_str == "boolean":
+                    python_type = bool
+
+                field = Field(description=details.get("description", ""))
+            else:
+                field = Field(description="")
+
+            schema_props[name] = field
+            annotations[name] = python_type
+
+        schema_class = type(
+            f"{self.name.title()}Args",
+            (BaseModel,),
+            {
+                "__annotations__": annotations,
+                "__module__": __name__,
+                **schema_props,
+            },
+        )
+
+        parent_tool = self
+        _name = parent_tool.name
+        _description = parent_tool.description
+
+        class StackOneCrewAITool(CrewAIBaseTool):
+            name: str = _name
+            description: str = _description
+            args_schema: type[BaseModel] = schema_class
+
+            def _run(self, **kwargs: Any) -> Any:
+                return parent_tool.execute(kwargs)
+
+        return StackOneCrewAITool()
+
     def set_account_id(self, account_id: str | None) -> None:
         """Set the account ID for this tool
 
@@ -558,6 +616,16 @@ def to_langchain(self) -> Sequence[BaseTool]:
         """
         return [tool.to_langchain() for tool in self.tools]
 
+    def to_crewai(self) -> list[Any]:
+        """Convert all tools to CrewAI format
+
+        Requires the ``crewai`` package (``pip install crewai``).
+
+        Returns:
+            List of tools as ``crewai.tools.BaseTool`` instances
+        """
+        return [tool.to_crewai() for tool in self.tools]
+
     def utility_tools(
         self,
         hybrid_alpha: float | None = None,

stackone_ai/toolset.py

@@ -306,7 +306,7 @@ def search_tools(
         query: str,
         *,
         connector: str | None = None,
-        top_k: int = 10,
+        top_k: int | None = None,
         min_score: float = 0.0,
         account_ids: list[str] | None = None,
         fallback_to_local: bool = True,
@@ -321,7 +321,7 @@ def search_tools(
             query: Natural language description of needed functionality
                 (e.g., "create employee", "send a message")
             connector: Optional provider/connector filter (e.g., "bamboohr", "slack")
-            top_k: Maximum number of tools to return (default: 10)
+            top_k: Maximum number of tools to return. If None, uses the backend default.
             min_score: Minimum similarity score threshold 0-1 (default: 0.0)
             account_ids: Optional account IDs (uses set_accounts() if not provided)
             fallback_to_local: If True, fall back to local BM25+TF-IDF search on API failure
@@ -372,11 +372,11 @@ def search_tools(
             ]
 
             # Step 3b: If not enough results, make per-connector calls for missing connectors
-            if len(filtered_results) < top_k and not connector:
+            if not connector and (top_k is None or len(filtered_results) < top_k):
                 found_connectors = {r.connector_key.lower() for r in filtered_results}
                 missing_connectors = available_connectors - found_connectors
                 for missing in missing_connectors:
-                    if len(filtered_results) >= top_k:
+                    if top_k is not None and len(filtered_results) >= top_k:
                         break
                     try:
                         extra = self.semantic_client.search(query=query, connector=missing, top_k=top_k)
@@ -385,7 +385,7 @@ def search_tools(
                                 fr.action_name for fr in filtered_results
                             }:
                                 filtered_results.append(r)
-                                if len(filtered_results) >= top_k:
+                                if top_k is not None and len(filtered_results) >= top_k:
                                     break
                     except SemanticSearchError:
                         continue
@@ -401,7 +401,7 @@ def search_tools(
                 if norm not in seen_names:
                     seen_names.add(norm)
                     deduped.append(r)
-            filtered_results = deduped[:top_k]
+            filtered_results = deduped[:top_k] if top_k is not None else deduped
 
             if not filtered_results:
                 return Tools([])
@@ -425,10 +425,11 @@ def search_tools(
             search_tool = utility.get_tool("tool_search")
 
             if search_tool:
+                fallback_limit = top_k * 3 if top_k is not None else 100
                 result = search_tool.execute(
                     {
                         "query": query,
-                        "limit": top_k * 3,  # Over-fetch to account for connector filtering
+                        "limit": fallback_limit,
                         "minScore": min_score,
                     }
                 )
@@ -441,7 +442,7 @@ def search_tools(
                     for name in matched_names
                     if name in tool_map and name.split("_")[0].lower() in filter_connectors
                 ]
-                return Tools(matched_tools[:top_k])
+                return Tools(matched_tools[:top_k] if top_k is not None else matched_tools)
 
             return all_tools
 
@@ -451,7 +452,7 @@ def search_action_names(
         *,
         connector: str | None = None,
         account_ids: list[str] | None = None,
-        top_k: int = 10,
+        top_k: int | None = None,
         min_score: float = 0.0,
     ) -> list[SemanticSearchResult]:
         """Search for action names without fetching tools.
@@ -465,15 +466,15 @@ def search_action_names(
             account_ids: Optional account IDs to scope results to connectors
                 available in those accounts (uses set_accounts() if not provided).
                 When provided, results are filtered to only matching connectors.
-            top_k: Maximum number of results (default: 10)
+            top_k: Maximum number of results. If None, uses the backend default.
             min_score: Minimum similarity score threshold 0-1 (default: 0.0)
 
         Returns:
             List of SemanticSearchResult with action names, scores, and metadata
 
         Examples:
             # Lightweight: inspect results before fetching
-            results = toolset.search_action_names("manage employees", top_k=10)
+            results = toolset.search_action_names("manage employees")
             for r in results:
                 print(f"{r.action_name}: {r.similarity_score:.2f}")
 
@@ -501,7 +502,7 @@ def search_action_names(
             response = self.semantic_client.search(
                 query=query,
                 connector=connector,
-                top_k=None if available_connectors else top_k,
+                top_k=top_k,
             )
         except SemanticSearchError as e:
             logger.warning("Semantic search failed: %s", e)
@@ -516,11 +517,11 @@ def search_action_names(
             results = [r for r in results if r.connector_key.lower() in connector_set]
 
             # If not enough results, make per-connector calls for missing connectors
-            if len(results) < top_k and not connector:
+            if not connector and (top_k is None or len(results) < top_k):
                 found_connectors = {r.connector_key.lower() for r in results}
                 missing_connectors = connector_set - found_connectors
                 for missing in missing_connectors:
-                    if len(results) >= top_k:
+                    if top_k is not None and len(results) >= top_k:
                         break
                     try:
                         extra = self.semantic_client.search(query=query, connector=missing, top_k=top_k)
@@ -529,7 +530,7 @@ def search_action_names(
                                 er.action_name for er in results
                             }:
                                 results.append(r)
-                                if len(results) >= top_k:
+                                if top_k is not None and len(results) >= top_k:
                                     break
                     except SemanticSearchError:
                         continue
@@ -553,7 +554,7 @@ def search_action_names(
                         description=r.description,
                     )
                 )
-        return normalized[:top_k]
+        return normalized[:top_k] if top_k is not None else normalized
 
     def _filter_by_provider(self, tool_name: str, providers: list[str]) -> bool:
         """Check if a tool name matches any of the provider filters