Architecture Overview

Relevant source files

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

• CLAUDE.md
• stackone_ai/tools.py
• stackone_ai/types.py
• README.md
• pyproject.toml
• tests/test_models.py

The StackOne AI SDK provides a unified Python interface for accessing SaaS tools through AI-friendly APIs. It supports integrations with OpenAI, LangChain, LangGraph, Pydantic AI, and the Model Context Protocol (MCP). The architecture ensures that the schema served to models matches the schema provided by the MCP server, preserving all metadata, constraints, and nested fields.

Sources: CLAUDE.md:7-10, README.md:1-15

Core Modules and Components

The SDK architecture consists of three primary modules that manage types, tool execution, and catalog discovery.

Module Definitions

Module	Description	Key Components
types.py	Defines core data structures, shared aliases, and the SDK error hierarchy.	ToolParameters, ToolMode, StackOneError
tools.py	Manages tool execution logic, header sanitization, and framework-specific converters.	StackOneTool, StackOneRpcTool, StackOneMcpTool, Tools
toolset.py	Handles account discovery, catalog caching, and high-level search/execution.	StackOneToolSet

Sources: CLAUDE.md:12-25, stackone_ai/types.py:1-45

Component Relationship Diagram

This diagram shows the relationship between the high-level ToolSet and individual tool execution paths.

The SDK uses StackOneToolSet as the entry point to discover accounts and fetch tool catalogs. These tools are then containerized and executed via either RPC or MCP protocols.
Sources: CLAUDE.md:18-25, stackone_ai/tools.py:125-500

Tool Execution Surfaces

The SDK supports two distinct calling surfaces with different argument shapes and execution paths. The choice depends on whether actions are discovered at runtime or bound to a model in advance.

Execution Path Comparison

Feature	RPC Path (fetch_tools)	MCP Path (search)
Tool Mode	individual	search_execute
Argument Shape	Flat-prefixed (e.g., body_variables)	Nested envelope (e.g., {"body": {"variables": {}}})
Logic Location	Client-side prefix splitting	Server-side meta tools
Best Use Case	Fixed, filtered tool sets for LLMs	Dynamic runtime action discovery

Sources: CLAUDE.md:27-46, README.md:118-135, stackone_ai/tools.py:530-580

Parameter Handling Logic

The SDK implements strict sanitization and splitting logic for tool arguments. StackOneRpcTool uses _split_envelope_params to map model-supplied flat keys into the standard RPC envelope (path, query, headers, and body).

Flat-prefixed keys (e.g., query_limit) are automatically routed to their respective locations in the API request envelope.
Sources: stackone_ai/tools.py:530-580, CLAUDE.md:38-42

Schema and Framework Integration

The SDK prioritizes schema integrity, ensuring that JSON Schema constraints (like enum, minimum, pattern) reach the LLM without loss.

Schema Pass-through

The to_openai_function and to_langchain methods pass the served schema through verbatim, stripping only the SDK-internal nullable marker to populate the JSON Schema required list. This prevents "lossy" rebuilds that might discard nested fields or validation bounds.

Sources: stackone_ai/tools.py:345-375, tests/test_models.py:535-580

Supported Integrations

1. OpenAI: to_openai() generates Chat Completions function tools. execute_openai_tool_calls() handles the model's response and returns tool messages.
2. LangChain: to_langchain() provides langchain_core.tools.BaseTool instances.
3. Pydantic AI: to_pydantic_ai() provides native support for pydantic-ai agents.

Sources: README.md:36-85, pyproject.toml:35-43, stackone_ai/tools.py:377-438

Error Hierarchy

All SDK exceptions derive from StackOneError. The hierarchy distinguishes between configuration issues and API runtime errors.

Class	Description
StackOneError	Base exception for all SDK errors.
StackOneAPIError	Raised when the API returns an error status code; contains status_code and response_body.
ToolsetError	Base for catalog-related issues.
ToolsetLoadError	Raised during failure to fetch tools from the MCP endpoint.

Sources: stackone_ai/types.py:46-75, stackone_ai/tools.py:200-240

Security and Sanitization

The architecture includes defensive measures against common injection vectors:

• Header Sanitization: _sanitise_headers uses an allowlist driven by the served schema. It drops any model-supplied headers not declared in the headers_* properties.
• File Downloads: _safe_basename reduces server-supplied filenames to safe basenames, preventing arbitrary-file-write primitives.
• Surrogate Handling: The SDK catches UnicodeEncodeError during JSON encoding to handle malformed tokens emitted by models.

Sources: stackone_ai/tools.py:305-340, stackone_ai/types.py:105-130, stackone_ai/tools.py:440-450

Architecture Summary

The StackOne AI SDK architecture centralizes around the concept that the "toolset is the served catalog." By leveraging MCP for tool discovery and offering dual calling surfaces (RPC and MCP), the SDK maintains a small context window for LLMs while providing access to hundreds of SaaS actions. Framework adapters ensure seamless integration with the modern AI ecosystem while maintaining strict schema fidelity.

Sources: CLAUDE.md:12-15, README.md:185-195