Overview

Relevant source files

• README.md
• pyproject.toml
• stackone_ai/__init__.py
• stackone_ai/feedback/__init__.py

The StackOne AI SDK is a Python library that provides a unified interface for AI agents to discover and execute actions across multiple SaaS platforms (HRIS, CRM, ATS, LMS). It abstracts the complexity of integrating with diverse APIs by offering dynamic tool discovery, intelligent filtering, and seamless conversion to popular AI framework formats.

Scope: This page covers the high-level architecture, core components, and system design patterns of the SDK. For specific usage patterns, see Quick Start. For detailed API documentation, see API Reference.

Related Pages:

• For tool discovery mechanics, see Tool Discovery via MCP
• For framework-specific integration patterns, see Framework Integrations
• For development setup and contribution guidelines, see Development Guide

---

System Purpose and Design Goals

The SDK addresses three primary challenges:

1. Dynamic Tool Discovery: SaaS integrations vary by customer. The SDK fetches available tools at runtime based on configured accounts rather than bundling static definitions.
2. Framework Agnostic: AI agents use diverse frameworks (OpenAI Functions, LangChain, CrewAI). The SDK provides format converters for seamless integration.
3. Intelligent Filtering: Customers may have dozens of connected SaaS platforms. The SDK offers glob-pattern filtering, provider selection, and hybrid search to reduce token overhead.

Sources: README.md1-50 pyproject.toml1-28

---

High-Level Architecture

Key Architectural Patterns:

Pattern	Implementation	Location
Facade	StackOneToolSet provides unified API for tool management	stackone_ai/toolset.py
Adapter	Format converters (to_openai_function(), to_langchain()) adapt tools to framework-specific formats	stackone_ai/models.py
Repository	Tools collection manages tool instances with lookup/filtering	stackone_ai/models.py
Proxy	_StackOneRpcTool proxies execution to remote RPC endpoint	stackone_ai/models.py
Strategy	Hybrid search in ToolIndex combines BM25 and TF-IDF algorithms	stackone_ai/meta_tools/tool_index.py

Sources: README.md10-28 stackone_ai/__init__.py1-11

---

Core Components and Their Relationships

Component Responsibilities:

Component	Primary Responsibility	Key Methods/Properties
StackOneToolSet	Entry point for SDK, manages API credentials and account configuration	fetch_tools(), set_accounts()
StackOneTool	Represents a single executable tool with schema and execution logic	execute(), call(), to_openai_function(), to_langchain()
Tools	Collection container providing tool lookup, filtering, and batch conversion	get_tool(), to_langchain(), meta_tools()
ToolIndex	Hybrid search engine for tool discovery using BM25 + TF-IDF	search(), initialized with hybrid_alpha=0.2
create_feedback_tool()	Factory for feedback collection tool	Returns StackOneTool instance

Sources: stackone_ai/__init__.py1-11 README.md53-69

---

Tool Lifecycle: Discovery to Execution

Lifecycle Stages:

1. Initialization: StackOneToolSet created with API key from environment (STACKONE_API_KEY) or explicit parameter
2. Discovery: fetch_tools() queries MCP service with filtering criteria
3. Client-Side Filtering: Glob patterns (actions=["hris_*"]) applied to tool names
4. Collection Assembly: Tools wrapped in Tools container with lookup methods
5. Execution: tool.call() or tool.execute() triggers RPC invocation with parameter validation

Sources: README.md53-69 README.md72-103

---

Integration Ecosystem

Integration Method Mapping:

Framework	Conversion Method	Output Type	Location
OpenAI	tool.to_openai_function()	OpenAI function calling dict	stackone_ai/models.py
LangChain	tool.to_langchain() or tools.to_langchain()	langchain_core.tools.BaseTool	stackone_ai/models.py
LangGraph	to_tool_node(langchain_tools)	ToolNode	stackone_ai/integrations/langgraph.py
CrewAI	Uses LangChain tools directly	langchain_core.tools.BaseTool	N/A (native compatibility)

Sources: README.md159-279 README.md23-27

---

Development Infrastructure

Infrastructure Components:

Component	Purpose	Key Features
Nix Flake	Reproducible development environments	Python 3.10-3.13 support, auto-installs dependencies
uv	Fast Python package manager	Manages uv.lock, replaces pip
just	Task automation	Provides install, lint, test, build, publish commands
ty	Type checker	Validates types with PEP 561 compliance (py.typed marker)
ruff	Linter/formatter	110-char line limit, PEP 8 compliance
release-please	Automated releases	Conventional commits → version bumps → PyPI publish

Sources: pyproject.toml1-119 README.md341-372

---

Dependency Graph

Dependency Rationale:

• pydantic: Validates tool schemas and parameters, ensures type safety at runtime
• httpx: Async-capable HTTP client, replaces requests (migration completed in v2.0.0)
• langchain-core: Provides BaseTool interface for LangChain/CrewAI compatibility
• bm25s: Implements BM25 algorithm for hybrid search in meta tools
• numpy: Required by bm25s for vector operations

Sources: pyproject.toml21-63 CHANGELOG.md52

---

Version and Compatibility

Attribute	Value	Notes
Current Version	2.1.1	Published 2026-01-22
Python Support	3.10, 3.11, 3.12, 3.13	Python 3.9 dropped in v2.0.0
License	MIT	See LICENSE
Package Name	stackone-ai	PyPI distribution
Repository	StackOneHQ/stackone-ai-python	GitHub

Breaking Changes in v2.0.0:

• Removed deprecated getTools() method (replaced by fetch_tools())
• Migrated from requests to httpx library
• Removed MCP server implementation (SDK now acts as MCP client only)
• Dropped Python 3.9 support

Sources: pyproject.toml1-20 stackone_ai/__init__.py11 CHANGELOG.md30-72

---

System Boundaries

What This SDK Does:

• Dynamically discovers available tools from StackOne MCP service
• Validates parameters against tool schemas
• Proxies execution to StackOne RPC endpoint
• Converts tool definitions to AI framework formats
• Provides hybrid search for tool discovery

What This SDK Does Not Do:

• Does not directly connect to SaaS platforms (routing handled by StackOne backend)
• Does not store or cache tool definitions (fetched on each fetch_tools() call)
• Does not manage OAuth flows or credentials for SaaS platforms (handled via StackOne accounts)
• Does not provide custom LLM implementations (integrates with existing frameworks)

Sources: README.md10-14