Adopt changes from the new API

Author: shashi-stackone

examples/agent_tool_search.py

@@ -10,13 +10,13 @@
    keeping token usage constant regardless of catalog size.
 
 This example demonstrates approach 2 with two patterns:
-- Raw client (Gemini): manual agent loop with ``toolset.execute()``
+- 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
-    - GOOGLE_API_KEY environment variable (for Gemini/LangChain)
+    - OPENAI_API_KEY environment variable
 
 Run with:
     uv run python examples/agent_tool_search.py
@@ -37,13 +37,13 @@
 from stackone_ai import StackOneToolSet
 
 
-def example_gemini() -> None:
-    """Raw client: Gemini via OpenAI-compatible API.
+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 (Gemini) — manual execution")
+    print("Example 1: Raw client (OpenAI) — manual execution")
     print("=" * 60)
     print()
 
@@ -54,9 +54,8 @@ def example_gemini() -> None:
         print()
         return
 
-    google_key = os.getenv("GOOGLE_API_KEY")
-    if not google_key:
-        print("Skipped: Set GOOGLE_API_KEY to run this example.")
+    if not os.getenv("OPENAI_API_KEY"):
+        print("Skipped: Set OPENAI_API_KEY to run this example.")
         print()
         return
 
@@ -71,18 +70,25 @@ def example_gemini() -> None:
     # 2. Get tools in OpenAI format
     openai_tools = toolset.openai(mode="search_and_execute")
 
-    # 3. Create Gemini client (OpenAI-compatible) and run agent loop
-    client = OpenAI(
-        api_key=google_key,
-        base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
-    )
+    # 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="gemini-3-pro-preview",
+            model="gpt-5.4",
             messages=messages,
             tools=openai_tools,
             tool_choice="auto",
@@ -123,15 +129,15 @@ def example_langchain() -> None:
     print()
 
     try:
-        from langchain_core.messages import AIMessage, HumanMessage, ToolMessage
-        from langchain_google_genai import ChatGoogleGenerativeAI
+        from langchain_core.messages import AIMessage, HumanMessage, SystemMessage, ToolMessage
+        from langchain_openai import ChatOpenAI
     except ImportError:
-        print("Skipped: pip install langchain-google-genai")
+        print("Skipped: pip install langchain-openai")
         print()
         return
 
-    if not os.getenv("GOOGLE_API_KEY"):
-        print("Skipped: Set GOOGLE_API_KEY to run this example.")
+    if not os.getenv("OPENAI_API_KEY"):
+        print("Skipped: Set OPENAI_API_KEY to run this example.")
         print()
         return
 
@@ -146,10 +152,21 @@ def example_langchain() -> 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 = ChatGoogleGenerativeAI(model="gemini-3-pro-preview").bind_tools(langchain_tools)
+    model = ChatOpenAI(model="gpt-5.4").bind_tools(langchain_tools)
 
     # 3. Run agent loop
-    messages = [HumanMessage(content="List my upcoming Calendly events for the next week.")]
+    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)
@@ -177,7 +194,7 @@ def main() -> None:
         print("Set STACKONE_API_KEY to run these examples.")
         return
 
-    example_gemini()
+    example_openai()
     example_langchain()
 
 

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,
     )

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}?")

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",

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(
             [

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/models.py

@@ -414,8 +414,10 @@ def to_langchain(self) -> BaseTool:
 
         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":
@@ -427,12 +429,18 @@ def to_langchain(self) -> BaseTool:
                 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/semantic_search.py

@@ -12,18 +12,16 @@
 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
+1. Fetch tools from linked accounts via MCP to discover available connectors
+2. Search EACH connector in parallel via the semantic search API (/actions/search)
+3. The search API returns results with full ``input_schema`` for each action
+4. Build executable tools directly from search results (no match-back needed)
+5. Deduplicate by action_id, sort by relevance score, apply top_k
 6. 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. The search API returns ``input_schema``
+with each result, so tools can be built directly without a separate fetch.
 
 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 +31,10 @@
 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 metadata
+(action_id, connector, score, description, input_schema) **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 +69,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 +93,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 +146,7 @@ def search(
         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 +204,4 @@ def search_action_names(
             )
         """
         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]