fix: examples

Author: Matt Carey

examples/error_handling.py

@@ -1,48 +1,62 @@
+"""
+This example demonstrates error handling when using the StackOne SDK.
+
+Run the following command to see the output:
+
+```bash
+uv run examples/error_handling.py
+```
+"""
+
+import os
+
 from dotenv import load_dotenv
 from stackone_ai import StackOneToolSet
+from stackone_ai.models import StackOneAPIError
 from stackone_ai.toolset import ToolsetConfigError, ToolsetLoadError
 
 load_dotenv()
 
 
 def error_handling() -> None:
+    # Example 1: Configuration error - missing API key
     try:
-        # Example 1: Handle missing API key
-        invalid_toolset = StackOneToolSet(api_key=None)
+        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)
-        # Config Error: API key must be provided either through api_key parameter or STACKONE_API_KEY environment variable
-
-    toolset = StackOneToolSet()
+        print("✗ Config Error:", e)
 
-    # Example 2: Handle unknown vertical
+    # Example 2: Invalid vertical error
     try:
-        tools = toolset.get_tools(vertical="unknown_vertical")
+        print("\n2. Testing invalid vertical...")
+        toolset = StackOneToolSet()
+        toolset.get_tools(vertical="invalid_vertical")
+        raise AssertionError("Expected ToolsetLoadError")
     except ToolsetLoadError as e:
-        print("Vertical Load Error:", e)
-        # Vertical Load Error: No spec file found for vertical: unknown_vertical
+        print("✗ Load Error:", e)
 
-    # Example 3: Handle API errors with account_id
-    tools = toolset.get_tools(vertical="crm", account_id="test_id")
-    try:
-        # Try with invalid ID
-        contacts_tool = tools.get_tool("get_contact")
-        if contacts_tool:
-            result = contacts_tool.execute({"id": "invalid_id"})
-    except Exception as e:
-        print(f"API Error: {e}")
-        # API Error: 400 Client Error: Bad Request for url: https://api.stackone.com/unified/crm/contacts/invalid_id
-
-    # Example 4: Handle missing account ID
-    tools_no_account = toolset.get_tools(vertical="crm", account_id=None)
+    # Example 3: API error - invalid request
     try:
-        list_contacts_tool = tools_no_account.get_tool("list_contacts")
-        if list_contacts_tool:
-            result = list_contacts_tool.execute()
-            print("Result without account ID:", result)
-    except Exception as e:
-        print(f"Error when account ID is missing: {e}")
-        # Error when account ID is missing: 501 Server Error: Not Implemented for url: https://api.stackone.com/unified/crm/contacts
+        print("\n3. Testing API error...")
+        toolset = StackOneToolSet()
+        tools = toolset.get_tools(vertical="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"
+
+        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)
 
 
 if __name__ == "__main__":

examples/file_upload_example.py examples/file_uploads.pyexamples/file_upload_example.py renamed to examples/file_uploads.py

@@ -43,15 +43,11 @@ def upload_employee_document() -> None:
         resume_file = Path(temp_dir) / "resume.pdf"
         resume_file.write_text(resume_content)
 
-        # Initialize StackOne
         toolset = StackOneToolSet()
         tools = toolset.get_tools(vertical="hris", account_id=account_id)
 
-        # Get the upload document tool
         upload_tool = tools.get_tool("hris_upload_employee_document")
-        if not upload_tool:
-            print("Upload tool not available")
-            return
+        assert upload_tool is not None
 
         with open(resume_file, "rb") as f:
             file_content = base64.b64encode(f.read()).decode()
@@ -65,10 +61,9 @@ def upload_employee_document() -> None:
             "file_format": {"value": "txt"},
         }
 
-        try:
-            upload_tool.execute(upload_params)
-        except Exception as e:
-            print(f"Error uploading document: {e}")
+        result = upload_tool.execute(upload_params)
+        assert result is not None
+        assert result.get("message") == "File uploaded successfully"
 
 
 if __name__ == "__main__":

examples/index.py

@@ -13,6 +13,12 @@
 ## Quick Start
 
 Here's a simple example. All examples are complete and runnable.
+
+You can even run the example directly from the command line:
+
+```bash
+uv run examples/index.py
+```
 """
 
 from dotenv import load_dotenv
@@ -45,14 +51,15 @@
 def quickstart():
     toolset = StackOneToolSet()
 
-    # Filter by vertical and add the account ID
-    tools = toolset.get_tools(vertical="hris", account_id=account_id)
+    # Supply a StackOne Account ID
+    tools = toolset.get_tools(account_id=account_id)
 
     # Use a specific tool
-    employee_tool = tools.get_tool("get_employee")
-    if employee_tool:
-        employee = employee_tool.execute({"id": employee_id})
-        print(employee)
+    employee_tool = tools.get_tool("hris_get_employee")
+    assert employee_tool is not None
+
+    employee = employee_tool.execute({"id": employee_id})
+    assert employee is not None
 
 
 if __name__ == "__main__":
@@ -61,10 +68,15 @@ def quickstart():
 """
 ## Next Steps
 
-Check out some examples:
+Check out some more documentation:
+
 - [Error Handling](error-handling.md)
-- [StackOne Account IDs](stackone_account_ids.md)
-- [Available Tools](available_tools.md)
+- [StackOne Account IDs](stackone-account-ids.md)
+- [Available Tools](available-tools.md)
+- [File Uploads](file-uploads.md)
+
+Or get started with an integration:
+
 - [OpenAI Integration](openai-integration.md)
 - [LangChain Integration](langchain-integration.md)
 - [CrewAI Integration](crewai-integration.md)

examples/langchain_integration.py

@@ -31,7 +31,9 @@ def langchain_integration() -> None:
         for tool_call in result.tool_calls:
             tool = tools.get_tool(tool_call["name"])
             if tool:
-                print(tool.execute(tool_call["args"]))
+                result = tool.execute(tool_call["args"])
+                assert result is not None
+                assert result.get("data") is not None
 
 
 if __name__ == "__main__":

examples/openai_integration.py

@@ -32,19 +32,19 @@ def openai_integration() -> None:
     client = OpenAI()
     toolset = StackOneToolSet()
 
-    # Get all tools but only convert the ones we need for this example
     all_tools = toolset.get_tools(vertical="hris", account_id=account_id)
 
-    # Only use the employee-related tools we need
     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)  # Create new Tools instance with filtered list
+    tools = type(all_tools)(filtered_tools)
     openai_tools = tools.to_openai()
 
     messages = [
@@ -68,9 +68,7 @@ def openai_integration() -> None:
             break
 
         results = handle_tool_calls(tools, response.choices[0].message.tool_calls)
-        if not results:
-            print("Error: Failed to execute tools")
-            break
+        assert results is not None
 
         messages.extend(
             [

examples/stackone_account_ids.py

@@ -22,11 +22,11 @@ def stackone_account_ids():
     tools.set_account_id("a_different_id")
 
     employee_tool = tools.get_tool("get_employee")
-    if employee_tool:
-        # You can even set the account ID on a per-tool basis
-        employee_tool.set_account_id("again_another_id")
+    assert employee_tool is not None
 
-        print(employee_tool.get_account_id())
+    # You can even set the account ID on a per-tool basis
+    employee_tool.set_account_id("again_another_id")
+    assert employee_tool.get_account_id() == "again_another_id"
 
 
 if __name__ == "__main__":

mkdocs.yml

@@ -48,5 +48,6 @@ nav:
       - OpenAI Integration: openai-integration.md
       - CrewAI Integration: crewai-integration.md
       - LangChain Integration: langchain-integration.md
-      - StackOne Account IDs: stackone_account_ids.md
-      - Error Handling: error-handling.md
+      - StackOne Account IDs: stackone-account-ids.md
+  - Error Handling: error-handling.md
+  - File Uploads: file-uploads.md