fix: openai create and write files

Author: Matt Carey

.cursor-rules/examples-standards.mdc

@@ -0,0 +1,104 @@
+---
+description: 
+globs: 
+---
+# Examples Standards
+
+Standards for creating and maintaining examples in the StackOne repository.
+
+<rule>
+name: examples_standards
+description: Standards for creating and maintaining examples for all functionality
+
+filters:
+  - type: path
+    pattern: "^examples/.*"
+  - type: path
+    pattern: "^packages/.*/.*"
+
+actions:
+  - type: suggest
+    message: |
+      When working with examples:
+
+      1. Location Requirements:
+         ```
+         examples/
+         ├── basic_usage/
+         │   ├── basic_tool_usage.py      # Basic usage examples
+         │   └── error_handling.py        # Error handling examples
+         ├── integrations/                # Integration examples
+         │   ├── openai_integration.py
+         │   └── other_integration.py
+         └── README.md                    # Examples documentation
+         ```
+
+      2. Example Requirements:
+         - Every public function/class needs at least one example
+         - Examples should be runnable Python scripts
+         - Include error handling cases
+         - Load credentials from .env
+         - Include type hints
+         - Follow the same code style as the main codebase
+         - Always use "gpt-4o-mini" as the model name in LLM examples
+         - Keep examples minimal and focused on demonstrating specific functionality
+
+      3. Documentation:
+         - Each example file should start with a docstring explaining its purpose
+         - Include expected output in comments
+         - Document any prerequisites (environment variables, etc)
+
+      4. Testing:
+         - Examples should be tested as part of CI
+         - Examples should work with the latest package version
+         - Include sample responses in comments
+
+examples:
+  - input: |
+      # Good example structure
+      import os
+      from dotenv import load_dotenv
+      from stackone_ai import StackOneToolSet
+      from openai import OpenAI
+
+      def main():
+          """Example showing basic usage of StackOneToolSet with OpenAI."""
+          load_dotenv()
+          
+          api_key = os.getenv("STACKONE_API_KEY")
+          if not api_key:
+              raise ValueError("STACKONE_API_KEY not found")
+          
+          client = OpenAI()
+          response = client.chat.completions.create(
+              model="gpt-4o-mini",  # Always use gpt-4o-mini in examples
+              messages=[{"role": "user", "content": "Hello"}]
+          )
+              
+          # Example code...
+
+      if __name__ == "__main__":
+          main()
+    output: "Correctly structured example"
+
+  - input: |
+      # Bad example - missing error handling, docs, types, wrong model name
+      from stackone_ai import StackOneToolSet
+      from openai import OpenAI
+
+      toolset = StackOneToolSet("hardcoded_key")
+      client = OpenAI()
+      response = client.chat.completions.create(
+          model="gpt-4",  # Wrong - should use gpt-4o-mini
+          messages=[{"role": "user", "content": "Hello"}]
+      )
+    output: "Incorrectly structured example"
+
+metadata:
+  priority: high
+  version: 1.0
+  tags:
+    - examples
+    - documentation
+    - testing
+</rule> 

.cursor/rules/examples-standards.mdc

@@ -1,7 +1,3 @@
----
-description: 
-globs: 
----
 # Examples Standards
 
 Standards for creating and maintaining examples in the StackOne repository.
@@ -40,6 +36,8 @@ actions:
          - Load credentials from .env
          - Include type hints
          - Follow the same code style as the main codebase
+         - Always use "gpt-4o-mini" as the model name in LLM examples
+         - Keep examples minimal and focused on demonstrating specific functionality
 
       3. Documentation:
          - Each example file should start with a docstring explaining its purpose
@@ -57,14 +55,21 @@ examples:
       import os
       from dotenv import load_dotenv
       from stackone_ai import StackOneToolSet
+      from openai import OpenAI
 
       def main():
-          """Example showing basic usage of StackOneToolSet."""
+          """Example showing basic usage of StackOneToolSet with OpenAI."""
           load_dotenv()
 
           api_key = os.getenv("STACKONE_API_KEY")
           if not api_key:
               raise ValueError("STACKONE_API_KEY not found")
+          
+          client = OpenAI()
+          response = client.chat.completions.create(
+              model="gpt-4o-mini",  # Always use gpt-4o-mini in examples
+              messages=[{"role": "user", "content": "Hello"}]
+          )
 
           # Example code...
 
@@ -73,12 +78,16 @@ examples:
     output: "Correctly structured example"
 
   - input: |
-      # Bad example - missing error handling, docs, types
+      # Bad example - missing error handling, docs, types, wrong model name
       from stackone_ai import StackOneToolSet
+      from openai import OpenAI
 
       toolset = StackOneToolSet("hardcoded_key")
-      tools = toolset.get_tools("crm")
-      result = tools["some_tool"].execute()
+      client = OpenAI()
+      response = client.chat.completions.create(
+          model="gpt-4",  # Wrong - should use gpt-4o-mini
+          messages=[{"role": "user", "content": "Hello"}]
+      )
     output: "Incorrectly structured example"
 
 metadata:

.vscode/settings.json

@@ -1,3 +1,4 @@
 {
-  "python.analysis.ignore": ["scripts/**"]
+  "python.analysis.ignore": ["scripts/**"],
+  "makefile.configureOnOpen": false
 }

Makefile

@@ -8,5 +8,11 @@ lint:
 test:
 	uv run pytest
 
+test-tools:
+	uv run pytest packages/stackone-ai
+
+test-examples:
+	uv run pytest examples
+
 mypy:
 	uv run mypy packages/stackone-ai/stackone_ai

examples/error_handling.py

@@ -1,18 +1,28 @@
 from dotenv import load_dotenv
 from stackone_ai import StackOneToolSet
+from stackone_ai.toolset import ToolsetConfigError, ToolsetLoadError
 
 load_dotenv()
 
 
 def error_handling() -> None:
+    try:
+        # Example 1: Handle missing API key
+        invalid_toolset = StackOneToolSet(api_key=None)
+    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()
 
-    # Example 1: Handle unknown vertical
-    tools = toolset.get_tools(vertical="unknown_vertical")
-    print("Tools for unknown vertical:", tools._tool_map)
-    # {}
+    # Example 2: Handle unknown vertical
+    try:
+        tools = toolset.get_tools(vertical="unknown_vertical")
+    except ToolsetLoadError as e:
+        print("Vertical Load Error:", e)
+        # Vertical Load Error: No spec file found for vertical: unknown_vertical
 
-    # Example 2: Handle API errors with account_id
+    # Example 3: Handle API errors with account_id
     tools = toolset.get_tools(vertical="crm", account_id="test_id")
     try:
         # Try with invalid ID
@@ -21,9 +31,9 @@ def error_handling() -> None:
             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
+        # API Error: 400 Client Error: Bad Request for url: https://api.stackone.com/unified/crm/contacts/invalid_id
 
-    # Example 3: Handle missing account ID
+    # Example 4: Handle missing account ID
     tools_no_account = toolset.get_tools(vertical="crm", account_id=None)
     try:
         list_contacts_tool = tools_no_account.get_tool("list_contacts")
@@ -32,7 +42,7 @@ def error_handling() -> None:
             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
+        # Error when account ID is missing: 501 Server Error: Not Implemented for url: https://api.stackone.com/unified/crm/contacts
 
 
 if __name__ == "__main__":

examples/openai_integration.py

@@ -1,9 +1,12 @@
 """
 This example demonstrates how to use StackOne tools with OpenAI's function calling.
 
+This example is runnable with the following command:
 ```bash
 uv run examples/openai_integration.py
 ```
+
+You can find out more about the OpenAI Function Calling API format [here](https://platform.openai.com/docs/guides/function-calling).
 """
 
 from dotenv import load_dotenv
@@ -28,7 +31,20 @@ def handle_tool_calls(tools, tool_calls) -> list[dict]:
 def openai_integration() -> None:
     client = OpenAI()
     toolset = StackOneToolSet()
-    tools = toolset.get_tools(vertical="hris", account_id=account_id)
+
+    # 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
+    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
     openai_tools = tools.to_openai()
 
     messages = [