feat: add proper filtering

Author: Matt Carey

examples/available_tools.py

@@ -1,16 +1,82 @@
 """
 Get available tools from your StackOne organisation based on the account id.
 
+This example demonstrates different ways to filter and organize tools:
+1. Getting all available tools
+2. Filtering by vertical
+3. Using multiple patterns for cross-vertical functionality
+4. Filtering by specific operations
+5. Combining multiple operation patterns
+
+# TODO: experimental - get_available_tools(account_id="your_account_id")
+
 ```bash
 uv run examples/available_tools.py
 ```
 """
 
+from dotenv import load_dotenv
+from stackone_ai import StackOneToolSet
+
+load_dotenv()
+
+
+def get_available_tools() -> None:
+    toolset = StackOneToolSet()
+
+    # First, get all tools
+    all_tools = toolset.get_tools()
+    assert len(all_tools) > 100, "Expected at least 100 tools in total"
+
+    # Then, let's get just HRIS tools using a vertical filter
+    hris_tools = toolset.get_tools("hris_*")
+    assert len(hris_tools) > 10, "Expected at least 10 HRIS tools"
+
+    # Now, let's get people-related tools across verticals
+    people_tools = toolset.get_tools(
+        [
+            "hris_*employee*",
+            "crm_*contact*",
+        ]
+    )
+    assert len(people_tools) > 20, "Expected at least 20 people-related tools"
+    for tool in people_tools:
+        assert "employee" in tool.name or "contact" in tool.name, (
+            f"Tool {tool.name} doesn't contain 'employee' or 'contact'"
+        )
+
+    # We can also filter by specific operations across all verticals
+    upload_tools = toolset.get_tools("*upload*")
+    assert len(upload_tools) > 0, "Expected at least one upload tool"
+    for tool in upload_tools:
+        assert "upload" in tool.name.lower(), f"Tool {tool.name} doesn't contain 'upload'"
+
+    # Get all tools except HRIS
+    non_hris_tools = toolset.get_tools("!hris_*")
+    assert len(non_hris_tools) > 0, "Expected at least one non-HRIS tool"
+    for tool in non_hris_tools:
+        assert not tool.name.startswith("hris_"), f"Tool {tool.name} should not be an HRIS tool"
 
-# TODO: Add examples
-def get_available_tools():
-    print("Getting available tools")
+    # Complex filtering with positive and negative patterns
+    list_tools = toolset.get_tools(
+        [
+            "*list*",  # Include list operations
+            "*search*",  # Include search operations
+            "!*delete*",  # Exclude delete operations
+            "!*remove*",  # Exclude remove operations
+        ]
+    )
+    assert len(list_tools) > 0, "Expected at least one list/search tool"
+    for tool in list_tools:
+        # Should match positive patterns
+        assert any(op in tool.name.lower() for op in ["list", "search"]), (
+            f"Tool {tool.name} doesn't contain 'list' or 'search'"
+        )
+        # Should not match negative patterns
+        assert not any(op in tool.name.lower() for op in ["delete", "remove"]), (
+            f"Tool {tool.name} contains excluded operation"
+        )
 
 
 if __name__ == "__main__":
-    print(get_available_tools())
+    get_available_tools()

examples/crewai_integration.py

@@ -17,13 +17,16 @@
 
 def crewai_integration():
     toolset = StackOneToolSet()
-    tools = toolset.get_tools(
-        vertical="hris",
-        account_id=account_id,
-    )
+    tools = toolset.get_tools("hris_*", account_id=account_id)
 
     # CrewAI uses LangChain tools natively
     langchain_tools = tools.to_langchain()
+    assert len(langchain_tools) > 0, "Expected at least one LangChain tool"
+
+    for tool in langchain_tools:
+        assert hasattr(tool, "name"), "Expected tool to have name"
+        assert hasattr(tool, "description"), "Expected tool to have description"
+        assert hasattr(tool, "_run"), "Expected tool to have _run method"
 
     agent = Agent(
         role="HR Manager",
@@ -42,7 +45,9 @@ def crewai_integration():
     )
 
     crew = Crew(agents=[agent], tasks=[task])
-    print(crew.kickoff())
+
+    result = crew.kickoff()
+    assert result is not None, "Expected result to be returned"
 
 
 if __name__ == "__main__":

examples/error_handling.py

@@ -20,43 +20,45 @@
 
 def error_handling() -> None:
     # Example 1: Configuration error - missing API key
+    original_api_key = os.environ.pop("STACKONE_API_KEY", None)
     try:
-        print("\n1. Testing configuration error (missing API key)...")
-        original_api_key = os.environ.pop("STACKONE_API_KEY", None)
         try:
             StackOneToolSet(api_key=None)
             raise AssertionError("Expected ToolsetConfigError")
-        finally:
-            if original_api_key:
-                os.environ["STACKONE_API_KEY"] = original_api_key
-    except ToolsetConfigError as e:
-        print("✗ Config Error:", e)
+        except ToolsetConfigError as e:
+            assert (
+                str(e)
+                == "API key must be provided either through api_key parameter or STACKONE_API_KEY environment variable"
+            )
+    finally:
+        if original_api_key:
+            os.environ["STACKONE_API_KEY"] = original_api_key
 
     # Example 2: Invalid vertical error
+    toolset = StackOneToolSet()
     try:
-        print("\n2. Testing invalid vertical...")
-        toolset = StackOneToolSet()
-        toolset.get_tools(vertical="invalid_vertical")
-        raise AssertionError("Expected ToolsetLoadError")
+        # Use a non-existent vertical to trigger error
+        tools = toolset.get_tools("nonexistent_vertical_*")
+        # If we get here, no tools were found but no error was raised
+        assert len(tools) == 0, "Expected no tools for nonexistent vertical"
     except ToolsetLoadError as e:
-        print("✗ Load Error:", e)
+        assert "Error loading tools" in str(e)
 
     # Example 3: API error - invalid request
-    try:
-        print("\n3. Testing API error...")
-        toolset = StackOneToolSet()
-        tools = toolset.get_tools(vertical="crm")
+    toolset = StackOneToolSet()
+    tools = toolset.get_tools("crm_*")
 
-        # Try to make an API call without required parameters
-        list_contacts = tools.get_tool("crm_list_contacts")
-        assert list_contacts is not None, "Expected crm_list_contacts tool to exist"
+    # Try to make an API call without required parameters
+    list_contacts = tools.get_tool("crm_list_contacts")
+    assert list_contacts is not None, "Expected crm_list_contacts tool to exist"
 
-        list_contacts.execute()
+    try:
+        # Execute without required parameters should raise error
+        list_contacts.execute({})
         raise AssertionError("Expected StackOneAPIError")
     except StackOneAPIError as e:
-        print("✗ API Error:", e)
-        print("  Status:", e.status_code)
-        print("  Response:", e.response_body)
+        assert e.status_code >= 400, "Expected error status code"
+        assert e.response_body is not None, "Expected error response body"
 
 
 if __name__ == "__main__":

examples/file_uploads.py

@@ -44,7 +44,7 @@ def upload_employee_document() -> None:
         resume_file.write_text(resume_content)
 
         toolset = StackOneToolSet()
-        tools = toolset.get_tools(vertical="hris", account_id=account_id)
+        tools = toolset.get_tools("hris_*", account_id=account_id)
 
         upload_tool = tools.get_tool("hris_upload_employee_document")
         assert upload_tool is not None

examples/index.py

@@ -51,8 +51,8 @@
 def quickstart():
     toolset = StackOneToolSet()
 
-    # Supply a StackOne Account ID
-    tools = toolset.get_tools(account_id=account_id)
+    # Get all HRIS-related tools
+    tools = toolset.get_tools("hris_*", account_id=account_id)
 
     # Use a specific tool
     employee_tool = tools.get_tool("hris_get_employee")

examples/langchain_integration.py

@@ -18,10 +18,20 @@
 
 def langchain_integration() -> None:
     toolset = StackOneToolSet()
-    tools = toolset.get_tools(vertical="hris", account_id=account_id)
+    tools = toolset.get_tools("hris_*", account_id=account_id)
 
+    # Convert to LangChain format and verify
     langchain_tools = tools.to_langchain()
+    assert len(langchain_tools) > 0, "Expected at least one LangChain tool"
 
+    # Verify tool structure
+    for tool in langchain_tools:
+        assert hasattr(tool, "name"), "Expected tool to have name"
+        assert hasattr(tool, "description"), "Expected tool to have description"
+        assert hasattr(tool, "_run"), "Expected tool to have _run method"
+        assert hasattr(tool, "args_schema"), "Expected tool to have args_schema"
+
+    # Create model with tools
     model = ChatOpenAI(model="gpt-4o-mini")
     model_with_tools = model.bind_tools(langchain_tools)
 

examples/langgraph_tool_node.py

@@ -1,15 +1,37 @@
 """
+TODO!!
+
 This example demonstrates how to use StackOne tools with LangGraph.
 
 ```bash
 uv run examples/langgraph_tool_node.py
 ```
 """
 
+from dotenv import load_dotenv
+from stackone_ai import StackOneToolSet
+
+load_dotenv()
+
+account_id = "45072196112816593343"
+employee_id = "c28xIQaWQ6MzM5MzczMDA2NzMzMzkwNzIwNA"
+
 
-# TODO: Add examples
 def langgraph_tool_node() -> None:
-    print("LangGraph tool node")
+    """Demonstrate basic LangGraph integration with StackOne tools."""
+    toolset = StackOneToolSet()
+    tools = toolset.get_tools("hris_*", account_id=account_id)
+
+    # Verify we have the tools we need
+    assert len(tools) > 0, "Expected at least one HRIS tool"
+    employee_tool = tools.get_tool("hris_get_employee")
+    assert employee_tool is not None, "Expected hris_get_employee tool"
+
+    # TODO: Add LangGraph specific integration
+    # For now, just verify the tools are properly configured
+    langchain_tools = tools.to_langchain()
+    assert len(langchain_tools) > 0, "Expected LangChain tools"
+    assert all(hasattr(tool, "_run") for tool in langchain_tools), "Expected all tools to have _run method"
 
 
 if __name__ == "__main__":

examples/openai_integration.py

@@ -32,19 +32,15 @@ def openai_integration() -> None:
     client = OpenAI()
     toolset = StackOneToolSet()
 
-    all_tools = toolset.get_tools(vertical="hris", account_id=account_id)
-
-    needed_tool_names = [
-        "hris_get_employee",
-        "hris_list_employee_employments",
-        "hris_get_employee_employment",
-    ]
-
-    # Filter tools to only the ones we need
-    # We need this because otherwise we can go over a context window limit
-    # TODO: better filtering options.
-    filtered_tools = [tool for tool in all_tools.tools if tool.name in needed_tool_names]
-    tools = type(all_tools)(filtered_tools)
+    # Filter tools to only the ones we need to avoid context window limits
+    tools = toolset.get_tools(
+        [
+            "hris_get_employee",
+            "hris_list_employee_employments",
+            "hris_get_employee_employment",
+        ],
+        account_id=account_id,
+    )
     openai_tools = tools.to_openai()
 
     messages = [
@@ -55,31 +51,41 @@ def openai_integration() -> None:
         },
     ]
 
-    while True:
-        response = client.chat.completions.create(
-            model="gpt-4o-mini",
-            messages=messages,
-            tools=openai_tools,
-            tool_choice="auto",
-        )
-
-        if not response.choices[0].message.tool_calls:
-            print("Response:", response.choices[0].message.content)
-            break
-
-        results = handle_tool_calls(tools, response.choices[0].message.tool_calls)
-        assert results is not None
-
-        messages.extend(
-            [
-                {"role": "assistant", "content": None, "tool_calls": response.choices[0].message.tool_calls},
-                {
-                    "role": "tool",
-                    "tool_call_id": response.choices[0].message.tool_calls[0].id,
-                    "content": str(results[0]),
-                },
-            ]
-        )
+    response = client.chat.completions.create(
+        model="gpt-4o-mini",
+        messages=messages,
+        tools=openai_tools,
+        tool_choice="auto",
+    )
+
+    # Verify we got a response with tool calls
+    assert response.choices[0].message.tool_calls is not None, "Expected tool calls in response"
+
+    # Handle the tool calls and verify results
+    results = handle_tool_calls(tools, response.choices[0].message.tool_calls)
+    assert results is not None and len(results) > 0, "Expected tool call results"
+    assert "data" in results[0], "Expected data in tool call result"
+
+    # Verify we can continue the conversation with the results
+    messages.extend(
+        [
+            {"role": "assistant", "content": None, "tool_calls": response.choices[0].message.tool_calls},
+            {
+                "role": "tool",
+                "tool_call_id": response.choices[0].message.tool_calls[0].id,
+                "content": str(results[0]),
+            },
+        ]
+    )
+
+    # Verify the final response
+    final_response = client.chat.completions.create(
+        model="gpt-4o-mini",
+        messages=messages,
+        tools=openai_tools,
+        tool_choice="auto",
+    )
+    assert final_response.choices[0].message.content is not None, "Expected final response content"
 
 
 if __name__ == "__main__":

examples/stackone_account_ids.py

@@ -15,13 +15,13 @@
 def stackone_account_ids():
     toolset = StackOneToolSet()
 
-    # Filter by vertical and set the account ID
-    tools = toolset.get_tools(vertical="hris", account_id="test_id")
+    # Filter by pattern and set the account ID
+    tools = toolset.get_tools("hris_*", account_id="test_id")
 
     # You can over write the account ID here..
     tools.set_account_id("a_different_id")
 
-    employee_tool = tools.get_tool("get_employee")
+    employee_tool = tools.get_tool("hris_get_employee")
     assert employee_tool is not None
 
     # You can even set the account ID on a per-tool basis