From 9c5ec7a5d6f7d9f2b95341cfd2f80b40538fc3ae Mon Sep 17 00:00:00 2001 From: Matt Carey Date: Tue, 25 Feb 2025 12:18:48 +0000 Subject: [PATCH] clean up docs formatting --- examples/available_tools.py | 25 +++++++++++++++++++------ examples/error_handling.py | 12 +++++++++--- examples/file_uploads.py | 6 ++++-- examples/index.py | 31 ++++++++++++++++--------------- examples/stackone_account_ids.py | 12 +++++++++--- 5 files changed, 57 insertions(+), 29 deletions(-) diff --git a/examples/available_tools.py b/examples/available_tools.py index 09f103f..c6cccf5 100644 --- a/examples/available_tools.py +++ b/examples/available_tools.py @@ -2,6 +2,7 @@ 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 @@ -25,15 +26,21 @@ def get_available_tools() -> None: toolset = StackOneToolSet() - # First, get all tools + """ + We can get all tools using the `get_tools` method. + """ 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 + """ + Then, let's get just HRIS tools using a filter. This filter accepts glob patterns. + """ 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 + """ + Filter with multiple patterns. This will return all tools that match either pattern (OR operator). + """ people_tools = toolset.get_tools( [ "hris_*employee*", @@ -46,19 +53,25 @@ def get_available_tools() -> None: f"Tool {tool.name} doesn't contain 'employee' or 'contact'" ) - # We can also filter by specific operations across all verticals + """ + Filter by specific operations across all verticals using a glob pattern. + """ 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 + """ + The exclude pattern is also supported. + """ 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" - # Complex filtering with positive and negative patterns + """ + More hectic example: + """ list_tools = toolset.get_tools( [ "*list*", # Include list operations diff --git a/examples/error_handling.py b/examples/error_handling.py index b1f4b1c..09fd41f 100644 --- a/examples/error_handling.py +++ b/examples/error_handling.py @@ -20,7 +20,9 @@ def error_handling() -> None: - # Example 1: Configuration error - missing API key + """ + Example 1: Configuration error - missing API key + """ original_api_key = os.environ.pop("STACKONE_API_KEY", None) try: try: @@ -35,7 +37,9 @@ def error_handling() -> None: if original_api_key: os.environ["STACKONE_API_KEY"] = original_api_key - # Example 2: Invalid vertical error + """ + Example 2: Invalid vertical error + """ toolset = StackOneToolSet() try: # Use a non-existent vertical to trigger error @@ -45,7 +49,9 @@ def error_handling() -> None: except ToolsetLoadError as e: assert "Error loading tools" in str(e) - # Example 3: API error - invalid request + """ + Example 3: API error - invalid request + """ toolset = StackOneToolSet() tools = toolset.get_tools("crm_*") diff --git a/examples/file_uploads.py b/examples/file_uploads.py index 84d35c1..eda5d8e 100644 --- a/examples/file_uploads.py +++ b/examples/file_uploads.py @@ -22,9 +22,10 @@ employee_id = "c28xIQaWQ6MzM5MzczMDA2NzMzMzkwNzIwNA" """ -## Resume content +# Resume content This is a sample resume content that will be uploaded to StackOne. + """ resume_content = """ @@ -44,9 +45,10 @@ """ -## Upload employee document +# Upload employee document This function uploads a resume using the `hris_upload_employee_document` tool. + """ diff --git a/examples/index.py b/examples/index.py index 4a92dea..96650dd 100644 --- a/examples/index.py +++ b/examples/index.py @@ -1,7 +1,7 @@ """ StackOne AI provides a unified interface for accessing various SaaS tools through AI-friendly APIs. -## Installation +# Installation ```bash # Using pip @@ -11,7 +11,7 @@ uv add stackone-ai ``` -## How to use these docs +# How to use these docs All examples are complete and runnable. We use [uv](https://docs.astral.sh/uv/getting-started/installation/) for python dependency management. @@ -23,13 +23,7 @@ uv run examples/index.py ``` -## Package Usage -""" - -from stackone_ai import StackOneToolSet - -""" -## Authentication +# Authentication Set the `STACKONE_API_KEY` environment variable: @@ -39,12 +33,13 @@ or load from a .env file: """ + from dotenv import load_dotenv load_dotenv() """ -## Account IDs +# Account IDs StackOne uses account IDs to identify different integrations. See the example [stackone-account-ids.md](stackone-account-ids.md) for more details. @@ -54,6 +49,12 @@ account_id = "45072196112816593343" +""" +# Quickstart +""" + +from stackone_ai import StackOneToolSet + def quickstart(): toolset = StackOneToolSet() @@ -73,7 +74,7 @@ def quickstart(): quickstart() """ -## Next Steps +# Next Steps Check out some more documentation: @@ -84,8 +85,8 @@ def quickstart(): Or get started with an integration: -- [OpenAI Integration](openai-integration.md) -- [LangChain Integration](langchain-integration.md) -- [CrewAI Integration](crewai-integration.md) -- [LangGraph Tool Node](langgraph-tool-node.md) +- [OpenAI](openai-integration.md) +- [LangChain](langchain-integration.md) +- [CrewAI](crewai-integration.md) +- [LangGraph](langgraph-tool-node.md) """ diff --git a/examples/stackone_account_ids.py b/examples/stackone_account_ids.py index cfa2fca..62bd6cd 100644 --- a/examples/stackone_account_ids.py +++ b/examples/stackone_account_ids.py @@ -16,16 +16,22 @@ def stackone_account_ids(): toolset = StackOneToolSet() - # Filter by pattern and set the account ID + """ + Set the account ID whilst getting tools. + """ tools = toolset.get_tools("hris_*", account_id="test_id") - # You can over write the account ID here.. + """ + You can over write the account ID on fetched tools. + """ tools.set_account_id("a_different_id") 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 + """ + 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"