feat: langchain tools (#2)

* feat: better docs

* feat: stackone ids

* feat: implement account ids

* fix: error handling

* fix: models, arg not defined

* feat: langchain tools

* fix: tools

* fix: tests

* fix: mypy

* fix: linting gh actions

* fis: env

* fix: deploy docs ci

* fix: ci

* feat: add oas

Author: mattzcarey

.env_example

@@ -1,3 +1,2 @@
 STACKONE_API_KEY=your_stackone_api_key
-STACKONE_ACCOUNT_ID=your_stackone_account_id
 OPENAI_API_KEY=your_openai_api_key

.github/workflows/docs.yml

@@ -4,9 +4,6 @@ on:
   push:
     branches:
       - main
-  pull_request:
-    branches:
-      - main
 
 permissions:
   contents: write

.github/workflows/lint.yml

@@ -18,7 +18,7 @@ jobs:
           enable-cache: true
 
       - name: Install dependencies
-        run: uv sync
+        run: uv sync --all-extras
 
       - name: Run Ruff
         uses: astral-sh/ruff-action@v3

.github/workflows/test.yml

@@ -8,7 +8,9 @@ on:
 jobs:
   test:
     runs-on: ubuntu-latest
-
+    env:
+      STACKONE_API_KEY: ${{ secrets.STACKONE_API_KEY }}
+      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
     steps:
       - uses: actions/checkout@v4
 
@@ -19,10 +21,7 @@ jobs:
           enable-cache: true
 
       - name: Install dependencies
-        run: uv sync
+        run: uv sync --all-extras
 
       - name: Run tests
         run: uv run pytest
-
-      - name: Run type checks
-        run: uv run mypy packages/stackone-core/

examples/api_reference.py

@@ -0,0 +1,16 @@
+"""
+Get available tools from your StackOne organisation based on the account id.
+
+```bash
+uv run examples/available_tools.py
+```
+"""
+
+
+# TODO: Add examples
+def get_available_tools():
+    print("Getting available tools")
+
+
+if __name__ == "__main__":
+    print(get_available_tools())

examples/available_tools.py

@@ -0,0 +1,49 @@
+"""
+This example demonstrates how to use StackOne tools with CrewAI.
+
+CrewAI uses LangChain tools natively.
+
+```bash
+uv run examples/crewai_integration.py
+```
+"""
+
+from crewai import Agent, Crew, Task
+from stackone_ai import StackOneToolSet
+
+account_id = "45072196112816593343"
+employee_id = "c28xIQaWQ6MzM5MzczMDA2NzMzMzkwNzIwNA"
+
+
+def crewai_integration():
+    toolset = StackOneToolSet()
+    tools = toolset.get_tools(
+        vertical="hris",
+        account_id=account_id,
+    )
+
+    # CrewAI uses LangChain tools natively
+    langchain_tools = tools.to_langchain()
+
+    agent = Agent(
+        role="HR Manager",
+        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",
+        tools=langchain_tools,
+        max_iter=2,
+    )
+
+    task = Task(
+        description="What is the employee with the id c28xIQaWQ6MzM5MzczMDA2NzMzMzkwNzIwNA?",
+        agent=agent,
+        expected_output="A JSON object containing the employee's information",
+    )
+
+    crew = Crew(agents=[agent], tasks=[task])
+    print(crew.kickoff())
+
+
+if __name__ == "__main__":
+    crewai_integration()

examples/basic_tool_usage.py

@@ -1,50 +1,39 @@
-import os
-
 from dotenv import load_dotenv
 from stackone_ai import StackOneToolSet
 
+load_dotenv()
 
-def demonstrate_error_handling():
-    # Load environment variables from root .env
-    load_dotenv()
-
-    api_key = os.getenv("STACKONE_API_KEY")
-    account_id = os.getenv("STACKONE_ACCOUNT_ID")
 
-    if not api_key:
-        raise ValueError("STACKONE_API_KEY not found in .env file")
-
-    toolset = StackOneToolSet(api_key=api_key)
+def error_handling() -> None:
+    toolset = StackOneToolSet()
 
     # Example 1: Handle unknown vertical
-    try:
-        tools = toolset.get_tools(vertical="unknown_vertical")
-        print("Tools for unknown vertical:", tools)  # Will print empty dict
-    except Exception as e:
-        print(f"Error getting tools: {e}")
+    tools = toolset.get_tools(vertical="unknown_vertical")
+    print("Tools for unknown vertical:", tools._tool_map)
+    # {}
 
     # Example 2: Handle API errors with account_id
-    tools = toolset.get_tools(vertical="crm", account_id=account_id)
-
-    # Example of handling various API errors
+    tools = toolset.get_tools(vertical="crm", account_id="test_id")
     try:
         # Try with invalid ID
-        contacts_tool = tools.get_tool("get_contacts")
+        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}")
+        # 400 Client Error: Bad Request for url: https://api.stackone.com/unified/crm/contacts/invalid_id
 
     # Example 3: Handle missing account ID
-    tools_no_account = toolset.get_tools(vertical="crm")  # No account_id
+    tools_no_account = toolset.get_tools(vertical="crm", account_id=None)
     try:
-        contacts_tool = tools_no_account.get_tool("get_contacts")
-        if contacts_tool:
-            result = contacts_tool.execute({"id": "123"})
+        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}")
+        # 501 Server Error: Not Implemented for url: https://api.stackone.com/unified/crm/contacts
 
 
 if __name__ == "__main__":
-    demonstrate_error_handling()
+    error_handling()