stackone-ai 2.3.0__tar.gz → 2.4.0__tar.gz

{stackone_ai-2.3.0 → stackone_ai-2.4.0}/.claude/rules/development-workflow.md

@@ -17,7 +17,7 @@ This rule provides code style guidelines and project conventions for the StackOn
 ## Type Annotations
 
 - Full type annotations required for all public APIs
-- Use Python 3.11+ typing features
+- Use Python 3.10+ typing features
 - Run `just ty` to verify type correctness
 - Strict ty configuration is enforced
 

stackone_ai-2.4.0/.envrc

@@ -0,0 +1,2 @@
+watch_file uv.lock
+use flake

{stackone_ai-2.3.0 → stackone_ai-2.4.0}/.gitignore

@@ -17,3 +17,7 @@ build/
 
 # Git hooks (managed by Nix)
 .pre-commit-config.yaml
+
+# Agent skills (managed by Nix via agent-skills-nix)
+.claude/skills
+.agents/skills

{stackone_ai-2.3.0 → stackone_ai-2.4.0}/.gitleaks.toml

@@ -6,9 +6,4 @@ useDefault = true
 
 [allowlist]
 description = "Global allowlist"
-paths = [
-    '''uv\.lock$''',
-    '''venv/''',
-    '''\.venv/''',
-    '''\.ruff_cache/''',
-]
+paths = ['''uv\.lock$''', '''venv/''', '''\.venv/''', '''\.ruff_cache/''']

stackone_ai-2.4.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "2.4.0"
+}

{stackone_ai-2.3.0 → stackone_ai-2.4.0}/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [2.4.0](https://github.com/StackOneHQ/stackone-ai-python/compare/stackone-ai-v2.3.1...stackone-ai-v2.4.0) (2026-03-06)
+
+
+### Features
+
+* **search:** Semantic Tool Search ([#149](https://github.com/StackOneHQ/stackone-ai-python/issues/149)) ([ac76d1b](https://github.com/StackOneHQ/stackone-ai-python/commit/ac76d1b12734f81ad29c2e30cf968ff2f1a1326c))
+* **skills:** add just-commands skill with dynamic context injection ([#133](https://github.com/StackOneHQ/stackone-ai-python/issues/133)) ([bf9f3fb](https://github.com/StackOneHQ/stackone-ai-python/commit/bf9f3fb46c4a6dbb55e76c83ceef0eb465b481fb))
+
+## [2.3.1](https://github.com/StackOneHQ/stackone-ai-python/compare/stackone-ai-v2.3.0...stackone-ai-v2.3.1) (2026-01-29)
+
+
+### Documentation
+
+* fix Python version requirement to 3.10+ ([#131](https://github.com/StackOneHQ/stackone-ai-python/issues/131)) ([ef2b4e3](https://github.com/StackOneHQ/stackone-ai-python/commit/ef2b4e3d06290d4fdc638bc66eec0c48b177c4f0))
+
 ## [2.3.0](https://github.com/StackOneHQ/stackone-ai-python/compare/stackone-ai-v2.1.1...stackone-ai-v2.3.0) (2026-01-29)
 
 

{stackone_ai-2.3.0 → stackone_ai-2.4.0}/CLAUDE.md

@@ -5,7 +5,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 ## Rules and Skills Structure
 
 - **Rules** (`.claude/rules/`): Automatically loaded based on file paths. Source of truth for project conventions.
-- **Skills** (`.claude/skills/`): Manually invoked for specific integrations.
+- **Skills** (`.agents/skills/`, `.claude/skills/`): Managed by Nix via [agent-skills-nix](https://github.com/Kyure-A/agent-skills-nix). Skills are sourced from [StackOneHQ/skills](https://github.com/StackOneHQ/skills) and installed automatically when entering `nix develop`.
 - **Cursor rules** (`.cursor/rules/`): Symlinks to `.claude/rules/` for consistency.
 
 ## Available Skills
@@ -27,26 +27,15 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 | **uv-scripts**               | `scripts/**/*.py`   | Utility script standards with UV                   |
 | **examples-standards**       | `examples/**/*`     | Example requirements and organization              |
 
-## Project Overview
-
-StackOne AI SDK is a Python library that provides a unified interface for accessing various SaaS tools through AI-friendly APIs. It acts as a bridge between AI applications and multiple SaaS platforms (HRIS, CRM, ATS, LMS, Marketing, etc.) with support for OpenAI, LangChain, CrewAI, and Model Context Protocol (MCP).
-
-## Essential Development Commands
+## Available Skills
 
-```bash
-# Setup and installation
-just install           # Install dependencies and pre-commit hooks
+| Skill             | Description                                  |
+| ----------------- | -------------------------------------------- |
+| **just-commands** | Available just commands (dynamically loaded) |
 
-# Code quality
-just lint             # Run ruff linting
-just lint-fix         # Auto-fix linting issues
-just ty               # Run type checking
+## Project Overview
 
-# Testing
-just test             # Run all tests
-just test-tools       # Run tool-specific tests
-just test-examples    # Run example tests
-```
+StackOne AI SDK is a Python library that provides a unified interface for accessing various SaaS tools through AI-friendly APIs with support for OpenAI, LangChain, CrewAI, and Model Context Protocol (MCP).
 
 ## Code Architecture
 
@@ -62,24 +51,13 @@ just test-examples    # Run example tests
    - `Tools`: Container for managing multiple tools
    - Format converters for different AI frameworks
 
-3. **OpenAPI Parser** (`stackone_ai/specs/parser.py`): Spec conversion
-   - Converts OpenAPI specs to tool definitions
-   - Handles file upload detection (`format: binary` → `type: file`)
-   - Resolves schema references
-
-### OpenAPI Specifications
-
-All tool definitions are generated from OpenAPI specs in `stackone_ai/oas/`:
-
-- `core.json`, `ats.json`, `crm.json`, `documents.json`, `hris.json`, `iam.json`, `lms.json`, `marketing.json`
-
 ## Key Development Patterns
 
 ### Tool Filtering
 
 ```python
 # Use glob patterns for tool selection
-tools = StackOneToolSet(include_tools=["hris_*", "!hris_create_*"])
+tools = StackOneToolSet(include_tools=["bamboohr_*", "!bamboohr_create_*"])
 ```
 
 ### Authentication
@@ -94,7 +72,7 @@ toolset = StackOneToolSet(
 
 ### Type Safety
 
-- Full type annotations required (Python 3.11+)
+- Full type annotations required (Python 3.10+)
 - Strict ty configuration
 - Use generics for better IDE support
 
@@ -108,7 +86,7 @@ toolset = StackOneToolSet(
 
 1. **Dependencies**: See `package-installation` rule for uv dependency management
 2. **Pre-commit**: Hooks configured for ruff and ty - run on all commits
-3. **Python Version**: Requires Python >=3.11
+3. **Python Version**: Requires Python >=3.10
 4. **Error Handling**: Custom exceptions (`StackOneError`, `StackOneAPIError`)
 5. **File Uploads**: Binary parameters auto-detected from OpenAPI specs
 6. **Context Window**: Tool loading warns when loading all tools (large context)

{stackone_ai-2.3.0 → stackone_ai-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stackone-ai
-Version: 2.3.0
+Version: 2.4.0
 Summary: agents performing actions on your SaaS
 Author-email: StackOne <support@stackone.com>
 License-File: LICENSE
@@ -48,10 +48,11 @@ StackOne AI provides a unified interface for accessing various SaaS tools throug
 - **Tool Calling**: Direct method calling with `tool.call()` for intuitive usage
 - **MCP-backed Dynamic Discovery**: Fetch tools at runtime via `fetch_tools()` with provider, action, and account filtering
 - **Advanced Tool Filtering**:
-  - Glob pattern filtering with patterns like `"hris_*"` and exclusions `"!hris_delete_*"`
+  - Glob pattern filtering with patterns like `"salesforce_*"` and exclusions `"!*_delete_*"`
   - Provider and action filtering
   - Multi-account support
-- **Utility Tools** (Beta): Dynamic tool discovery and execution based on natural language queries
+- **Semantic Search**: AI-powered tool discovery using natural language queries
+- **Search Tool**: Callable tool discovery for agent loops via `get_search_tool()`
 - Integration with popular AI frameworks:
   - OpenAI Functions
   - LangChain Tools
@@ -60,7 +61,7 @@ StackOne AI provides a unified interface for accessing various SaaS tools throug
 
 ## Requirements
 
-- Python 3.11+
+- Python 3.10+
 
 ## Installation
 
@@ -90,10 +91,10 @@ toolset = StackOneToolSet()  # Uses STACKONE_API_KEY env var
 # Or explicitly: toolset = StackOneToolSet(api_key="your-api-key")
 
 # Get HRIS-related tools with glob patterns
-tools = toolset.fetch_tools(actions=["hris_*"], account_ids=["your-account-id"])
+tools = toolset.fetch_tools(actions=["bamboohr_*"], account_ids=["your-account-id"])
 
 # Use a specific tool with the call method
-employee_tool = tools.get_tool("hris_get_employee")
+employee_tool = tools.get_tool("bamboohr_get_employee")
 # Call with keyword arguments
 employee = employee_tool.call(id="employee-id")
 # Or with traditional execute method
@@ -139,9 +140,9 @@ tools = toolset.fetch_tools(providers=["hibob"])
 - **`account_ids`**: Filter tools by account IDs. Tools will be loaded for each specified account.
 - **`providers`**: Filter by provider names (e.g., `["hibob", "bamboohr"]`). Case-insensitive matching.
 - **`actions`**: Filter by action patterns with glob support:
-  - Exact match: `["hris_list_employees"]`
+  - Exact match: `["bamboohr_list_employees"]`
   - Glob pattern: `["*_list_employees"]` matches all tools ending with `_list_employees`
-  - Provider prefix: `["hris_*"]` matches all HRIS tools
+  - Provider prefix: `["bamboohr_*"]` matches all BambooHR tools
 
 ## Implicit Feedback (Beta)
 
@@ -201,7 +202,7 @@ from stackone_ai import StackOneToolSet
 
 # Initialize StackOne tools
 toolset = StackOneToolSet()
-tools = toolset.fetch_tools(actions=["hris_*"], account_ids=["your-account-id"])
+tools = toolset.fetch_tools(actions=["bamboohr_*"], account_ids=["your-account-id"])
 
 # Convert to LangChain format
 langchain_tools = tools.to_langchain()
@@ -248,7 +249,7 @@ from stackone_ai.integrations.langgraph import to_tool_node, bind_model_with_too
 
 # Prepare tools
 toolset = StackOneToolSet()
-tools = toolset.fetch_tools(actions=["hris_*"], account_ids=["your-account-id"])
+tools = toolset.fetch_tools(actions=["bamboohr_*"], account_ids=["your-account-id"])
 langchain_tools = tools.to_langchain()
 
 class State(TypedDict):
@@ -286,7 +287,7 @@ from stackone_ai import StackOneToolSet
 
 # Get tools and convert to LangChain format
 toolset = StackOneToolSet()
-tools = toolset.fetch_tools(actions=["hris_*"], account_ids=["your-account-id"])
+tools = toolset.fetch_tools(actions=["bamboohr_*"], account_ids=["your-account-id"])
 langchain_tools = tools.to_langchain()
 
 # Create CrewAI agent with StackOne tools
@@ -328,7 +329,7 @@ feedback_tool = tools.get_tool("tool_feedback")
 result = feedback_tool.call(
     feedback="The HRIS tools are working great! Very fast response times.",
     account_id="acc_123456",
-    tool_names=["hris_list_employees", "hris_get_employee"]
+    tool_names=["bamboohr_list_employees", "bamboohr_get_employee"]
 )
 ```
 
@@ -337,26 +338,59 @@ result = feedback_tool.call(
 - "Are you ok with sending feedback to StackOne? The LLM will take care of sending it."
 - Only call the tool after the user explicitly agrees.
 
-## Utility Tools (Beta)
+## Search Tool
 
-Utility tools enable dynamic tool discovery and execution without hardcoding tool names.
+Search for tools using natural language queries. Works with both semantic (cloud) and local BM25+TF-IDF search.
 
 ### Basic Usage
 
 ```python
-# Get utility tools for dynamic discovery
-tools = toolset.fetch_tools(actions=["hris_*"])
-utility_tools = tools.utility_tools()
+# Get a callable search tool
+toolset = StackOneToolSet()
+all_tools = toolset.fetch_tools(account_ids=["your-account-id"])
+search_tool = toolset.get_search_tool()
 
-# Search for relevant tools using natural language
-filter_tool = utility_tools.get_tool("tool_search")
-results = filter_tool.call(query="manage employees", limit=5)
+# Search for relevant tools — returns a Tools collection
+tools = search_tool("manage employees", top_k=5)
 
-# Execute discovered tools dynamically
-execute_tool = utility_tools.get_tool("tool_execute")
-result = execute_tool.call(toolName="hris_list_employees", params={"limit": 10})
+# Execute a discovered tool directly
+tools[0](limit=10)
 ```
 
+## Semantic Search
+
+Discover tools using natural language instead of exact names. Queries like "onboard new hire" resolve to the right actions even when the tool is called `bamboohr_create_employee`.
+
+```python
+from stackone_ai import StackOneToolSet
+
+toolset = StackOneToolSet()
+
+# Search by intent — returns Tools collection ready for any framework
+tools = toolset.search_tools("manage employee records", account_ids=["your-account-id"], top_k=5)
+openai_tools = tools.to_openai()
+
+# Lightweight: inspect results without fetching full tool definitions
+results = toolset.search_action_names("time off requests", top_k=5)
+```
+
+### Search Modes
+
+Control which search backend `search_tools()` uses via the `search` parameter:
+
+```python
+# "auto" (default) — tries semantic search first, falls back to local
+tools = toolset.search_tools("manage employees", search="auto")
+
+# "semantic" — semantic API only, raises if unavailable
+tools = toolset.search_tools("manage employees", search="semantic")
+
+# "local" — local BM25+TF-IDF only, no semantic API call
+tools = toolset.search_tools("manage employees", search="local")
+```
+
+Results are automatically scoped to connectors in your linked accounts. See [Semantic Search Example](examples/semantic_search_example.py) for `SearchTool` (`get_search_tool`) integration, OpenAI, and LangChain patterns.
+
 ## Examples
 
 For more examples, check out the [examples/](examples/) directory:
@@ -366,7 +400,8 @@ For more examples, check out the [examples/](examples/) directory:
 - [OpenAI Integration](examples/openai_integration.py)
 - [LangChain Integration](examples/langchain_integration.py)
 - [CrewAI Integration](examples/crewai_integration.py)
-- [Utility Tools](examples/utility_tools_example.py)
+- [Search Tool](examples/search_tool_example.py)
+- [Semantic Search](examples/semantic_search_example.py)
 
 ## Development
 

{stackone_ai-2.3.0 → stackone_ai-2.4.0}/README.md

@@ -16,10 +16,11 @@ StackOne AI provides a unified interface for accessing various SaaS tools throug
 - **Tool Calling**: Direct method calling with `tool.call()` for intuitive usage
 - **MCP-backed Dynamic Discovery**: Fetch tools at runtime via `fetch_tools()` with provider, action, and account filtering
 - **Advanced Tool Filtering**:
-  - Glob pattern filtering with patterns like `"hris_*"` and exclusions `"!hris_delete_*"`
+  - Glob pattern filtering with patterns like `"salesforce_*"` and exclusions `"!*_delete_*"`
   - Provider and action filtering
   - Multi-account support
-- **Utility Tools** (Beta): Dynamic tool discovery and execution based on natural language queries
+- **Semantic Search**: AI-powered tool discovery using natural language queries
+- **Search Tool**: Callable tool discovery for agent loops via `get_search_tool()`
 - Integration with popular AI frameworks:
   - OpenAI Functions
   - LangChain Tools
@@ -28,7 +29,7 @@ StackOne AI provides a unified interface for accessing various SaaS tools throug
 
 ## Requirements
 
-- Python 3.11+
+- Python 3.10+
 
 ## Installation
 
@@ -58,10 +59,10 @@ toolset = StackOneToolSet()  # Uses STACKONE_API_KEY env var
 # Or explicitly: toolset = StackOneToolSet(api_key="your-api-key")
 
 # Get HRIS-related tools with glob patterns
-tools = toolset.fetch_tools(actions=["hris_*"], account_ids=["your-account-id"])
+tools = toolset.fetch_tools(actions=["bamboohr_*"], account_ids=["your-account-id"])
 
 # Use a specific tool with the call method
-employee_tool = tools.get_tool("hris_get_employee")
+employee_tool = tools.get_tool("bamboohr_get_employee")
 # Call with keyword arguments
 employee = employee_tool.call(id="employee-id")
 # Or with traditional execute method
@@ -107,9 +108,9 @@ tools = toolset.fetch_tools(providers=["hibob"])
 - **`account_ids`**: Filter tools by account IDs. Tools will be loaded for each specified account.
 - **`providers`**: Filter by provider names (e.g., `["hibob", "bamboohr"]`). Case-insensitive matching.
 - **`actions`**: Filter by action patterns with glob support:
-  - Exact match: `["hris_list_employees"]`
+  - Exact match: `["bamboohr_list_employees"]`
   - Glob pattern: `["*_list_employees"]` matches all tools ending with `_list_employees`
-  - Provider prefix: `["hris_*"]` matches all HRIS tools
+  - Provider prefix: `["bamboohr_*"]` matches all BambooHR tools
 
 ## Implicit Feedback (Beta)
 
@@ -169,7 +170,7 @@ from stackone_ai import StackOneToolSet
 
 # Initialize StackOne tools
 toolset = StackOneToolSet()
-tools = toolset.fetch_tools(actions=["hris_*"], account_ids=["your-account-id"])
+tools = toolset.fetch_tools(actions=["bamboohr_*"], account_ids=["your-account-id"])
 
 # Convert to LangChain format
 langchain_tools = tools.to_langchain()
@@ -216,7 +217,7 @@ from stackone_ai.integrations.langgraph import to_tool_node, bind_model_with_too
 
 # Prepare tools
 toolset = StackOneToolSet()
-tools = toolset.fetch_tools(actions=["hris_*"], account_ids=["your-account-id"])
+tools = toolset.fetch_tools(actions=["bamboohr_*"], account_ids=["your-account-id"])
 langchain_tools = tools.to_langchain()
 
 class State(TypedDict):
@@ -254,7 +255,7 @@ from stackone_ai import StackOneToolSet
 
 # Get tools and convert to LangChain format
 toolset = StackOneToolSet()
-tools = toolset.fetch_tools(actions=["hris_*"], account_ids=["your-account-id"])
+tools = toolset.fetch_tools(actions=["bamboohr_*"], account_ids=["your-account-id"])
 langchain_tools = tools.to_langchain()
 
 # Create CrewAI agent with StackOne tools
@@ -296,7 +297,7 @@ feedback_tool = tools.get_tool("tool_feedback")
 result = feedback_tool.call(
     feedback="The HRIS tools are working great! Very fast response times.",
     account_id="acc_123456",
-    tool_names=["hris_list_employees", "hris_get_employee"]
+    tool_names=["bamboohr_list_employees", "bamboohr_get_employee"]
 )
 ```
 
@@ -305,26 +306,59 @@ result = feedback_tool.call(
 - "Are you ok with sending feedback to StackOne? The LLM will take care of sending it."
 - Only call the tool after the user explicitly agrees.
 
-## Utility Tools (Beta)
+## Search Tool
 
-Utility tools enable dynamic tool discovery and execution without hardcoding tool names.
+Search for tools using natural language queries. Works with both semantic (cloud) and local BM25+TF-IDF search.
 
 ### Basic Usage
 
 ```python
-# Get utility tools for dynamic discovery
-tools = toolset.fetch_tools(actions=["hris_*"])
-utility_tools = tools.utility_tools()
+# Get a callable search tool
+toolset = StackOneToolSet()
+all_tools = toolset.fetch_tools(account_ids=["your-account-id"])
+search_tool = toolset.get_search_tool()
 
-# Search for relevant tools using natural language
-filter_tool = utility_tools.get_tool("tool_search")
-results = filter_tool.call(query="manage employees", limit=5)
+# Search for relevant tools — returns a Tools collection
+tools = search_tool("manage employees", top_k=5)
 
-# Execute discovered tools dynamically
-execute_tool = utility_tools.get_tool("tool_execute")
-result = execute_tool.call(toolName="hris_list_employees", params={"limit": 10})
+# Execute a discovered tool directly
+tools[0](limit=10)
 ```
 
+## Semantic Search
+
+Discover tools using natural language instead of exact names. Queries like "onboard new hire" resolve to the right actions even when the tool is called `bamboohr_create_employee`.
+
+```python
+from stackone_ai import StackOneToolSet
+
+toolset = StackOneToolSet()
+
+# Search by intent — returns Tools collection ready for any framework
+tools = toolset.search_tools("manage employee records", account_ids=["your-account-id"], top_k=5)
+openai_tools = tools.to_openai()
+
+# Lightweight: inspect results without fetching full tool definitions
+results = toolset.search_action_names("time off requests", top_k=5)
+```
+
+### Search Modes
+
+Control which search backend `search_tools()` uses via the `search` parameter:
+
+```python
+# "auto" (default) — tries semantic search first, falls back to local
+tools = toolset.search_tools("manage employees", search="auto")
+
+# "semantic" — semantic API only, raises if unavailable
+tools = toolset.search_tools("manage employees", search="semantic")
+
+# "local" — local BM25+TF-IDF only, no semantic API call
+tools = toolset.search_tools("manage employees", search="local")
+```
+
+Results are automatically scoped to connectors in your linked accounts. See [Semantic Search Example](examples/semantic_search_example.py) for `SearchTool` (`get_search_tool`) integration, OpenAI, and LangChain patterns.
+
 ## Examples
 
 For more examples, check out the [examples/](examples/) directory:
@@ -334,7 +368,8 @@ For more examples, check out the [examples/](examples/) directory:
 - [OpenAI Integration](examples/openai_integration.py)
 - [LangChain Integration](examples/langchain_integration.py)
 - [CrewAI Integration](examples/crewai_integration.py)
-- [Utility Tools](examples/utility_tools_example.py)
+- [Search Tool](examples/search_tool_example.py)
+- [Semantic Search](examples/semantic_search_example.py)
 
 ## Development