OpenAI Integration

Relevant source files

The following files were used as context for generating this wiki page:

• examples/openai_integration.py
• stackone_ai/tools.py
• stackone_ai/types.py
• tests/test_models.py
• README.md
• CLAUDE.md

OpenAI Integration in the StackOne AI SDK provides a bridge between discovered SaaS tools and OpenAI's Chat Completions API. It translates served tool catalogs into OpenAI's function-calling format and automates the execution of tool calls generated by Large Language Models (LLMs).

The integration ensures that tool schemas reach the model intact, preserving constraints like enums, patterns, and nested object structures. It handles the full round-trip of tool interaction, including error reporting and binary content serialization.

Sources: README.md:21-26, CLAUDE.md:144-154, stackone_ai/tools.py:1-9

Core Components and Workflow

The integration relies on two primary classes to manage the conversion and execution lifecycle: StackOneTool and Tools.

Process Flow

The following sequence diagram illustrates the interaction between the User, OpenAI API, and the StackOne SDK:

The diagram shows how the SDK manages the translation layer, allowing the LLM to interact with SaaS providers via standard OpenAI function calls.

Sources: examples/openai_integration.py:44-77, README.md:73-90

Schema Translation

The StackOneTool.to_openai_function() method converts internal tool definitions into OpenAI-compatible JSON schemas.

Key Translation Rules

• Constraint Preservation: Keywords such as format, pattern, minimum, maximum, and oneOf are passed through to the model verbatim.
• Nullability Handling: The SDK's internal nullable marker is stripped and used to derive the standard JSON Schema required list.
• Nested Structures: Nested objects and their properties are preserved to ensure the model understands the full argument envelope.

Sources: stackone_ai/tools.py:657-695, tests/test_models.py:537-628

Schema Conversion Mapping

SDK Property	OpenAI Function Equivalent	Description
name	function.name	The unique identifier for the tool.
description	function.description	Natural language instructions for the LLM.
parameters.properties	function.parameters.properties	The input fields allowed by the tool.
nullable: False	function.parameters.required	Properties marked non-nullable are added to this list.

Sources: stackone_ai/tools.py:657-695, stackone_ai/types.py:270-279

Execution Management

The Tools.execute_openai_tool_calls() method processes a list of tool calls returned by the OpenAI API.

Execution Features

1. Serialization: Uses a custom _json_default handler to convert binary results (from file downloads) into Base64-encoded strings, preventing JSON encoding failures.
2. Error Resilience: Caught exceptions (like StackOneAPIError or ValueError) are formatted as error messages within the tool response rather than terminating the program. This allows the LLM to see the error and potentially retry.
3. Order Preservation: The assistant turn must be appended to the message history before the tool results to comply with OpenAI API requirements.

Sources: stackone_ai/tools.py:978-984, stackone_ai/tools.py:1007-1033, examples/openai_integration.py:69-73

Handling Binary Content

When a tool returns raw bytes (e.g., a PDF download), the integration ensures the data is model-readable:

def _json_default(value: Any) -> Any:
    if isinstance(value, bytes):
        return base64.b64encode(value).decode("ascii")
    return str(value)

Sources: stackone_ai/tools.py:978-984

Integration Implementation

Typical implementation involves filtering tools to stay within the model's context window (maximum 128 tools for OpenAI).

from openai import OpenAI
from stackone_ai import StackOneToolSet

toolset = StackOneToolSet()
# Narrow filter to keep context window clean
tools = toolset.fetch_tools(actions=["*_list_*"])
openai_tools = tools.to_openai()[:20] 

client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "List recent records"}],
    tools=openai_tools
)

# Handle tool calls
message = response.choices[0].message
if message.tool_calls:
    results = tools.execute_openai_tool_calls(message.tool_calls)

Sources: README.md:73-83, examples/openai_integration.py:44-77

Summary

OpenAI Integration simplifies SaaS automation by providing a robust translation layer. It automates schema conversion while maintaining strict technical fidelity to the underlying SaaS definitions. By handling error surfacing and binary serialization, it allows developers to build resilient agents that can discover and execute complex SaaS operations through standard OpenAI API patterns.