stackone-ai 0.0.4__tar.gz → 0.3.1__tar.gz

{stackone_ai-0.0.4 → stackone_ai-0.3.1}/.github/workflows/docs.yml

@@ -12,10 +12,10 @@ jobs:
   deploy:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v4
+        uses: astral-sh/setup-uv@e92bafb6253dcd438e0484186d7669ea7a8ca1cc # v6.4.3
         with:
           python-version: "3.11"
           enable-cache: true
@@ -30,7 +30,7 @@ jobs:
 
       - name: Deploy to GitHub Pages
         if: github.ref == 'refs/heads/main'
-        uses: peaceiris/actions-gh-pages@v3
+        uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4.0.0
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: ./site

{stackone_ai-0.0.4 → stackone_ai-0.3.1}/.github/workflows/lint.yml

@@ -9,10 +9,10 @@ jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v5
+        uses: astral-sh/setup-uv@e92bafb6253dcd438e0484186d7669ea7a8ca1cc # v6.4.3
         with:
           python-version: "3.11"
           enable-cache: true
@@ -21,7 +21,7 @@ jobs:
         run: uv sync --all-extras
 
       - name: Run Ruff
-        uses: astral-sh/ruff-action@v3
+        uses: astral-sh/ruff-action@0c50076f12c38c3d0115b7b519b54a91cb9cf0ad # v3.5.0
         with:
           args: check .
 

{stackone_ai-0.0.4 → stackone_ai-0.3.1}/.github/workflows/release.yml

@@ -13,19 +13,19 @@ jobs:
   release-please:
     runs-on: ubuntu-latest
     steps:
-      - uses: google-github-actions/release-please-action@v4
+      - uses: google-github-actions/release-please-action@e4dc86ba9405554aeba3c6bb2d169500e7d3b4ee # v4.1.1
         id: release
         with:
           config-file: .release-please-config.json
           manifest-file: .release-please-manifest.json
 
       # Only release to PyPI when a new release is created
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         if: ${{ steps.release.outputs.release_created }}
 
       - name: Install uv
         if: ${{ steps.release.outputs.release_created }}
-        uses: astral-sh/setup-uv@v5
+        uses: astral-sh/setup-uv@e92bafb6253dcd438e0484186d7669ea7a8ca1cc # v6.4.3
         with:
           python-version: "3.11"
           enable-cache: true

{stackone_ai-0.0.4 → stackone_ai-0.3.1}/.github/workflows/test.yml

@@ -12,10 +12,10 @@ jobs:
       STACKONE_API_KEY: ${{ secrets.STACKONE_API_KEY }}
       OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v5
+        uses: astral-sh/setup-uv@e92bafb6253dcd438e0484186d7669ea7a8ca1cc # v6.4.3
         with:
           python-version: "3.11"
           enable-cache: true

stackone_ai-0.3.1/.mcp.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "context7": {
+      "type": "http",
+      "url": "https://mcp.context7.com/mcp"
+    },
+    "grep": {
+      "type": "http",
+      "url": "https://mcp.grep.app"
+    }
+  }
+}

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

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

{stackone_ai-0.0.4 → stackone_ai-0.3.1}/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## [0.3.1](https://github.com/StackOneHQ/stackone-ai-python/compare/stackone-ai-v0.3.0...stackone-ai-v0.3.1) (2025-08-19)
+
+
+### Documentation
+
+* add comprehensive LangChain integration section to README ([#20](https://github.com/StackOneHQ/stackone-ai-python/issues/20)) ([cbf7f68](https://github.com/StackOneHQ/stackone-ai-python/commit/cbf7f68e889839f9a501ad8f2cd47c468ffff47e))
+* rename meta tools ([#27](https://github.com/StackOneHQ/stackone-ai-python/issues/27)) ([a9ebc03](https://github.com/StackOneHQ/stackone-ai-python/commit/a9ebc032f784863913b28d4ad3850b80bafee5f4))
+
+## [0.3.0](https://github.com/StackOneHQ/stackone-ai-python/compare/stackone-ai-v0.0.4...stackone-ai-v0.3.0) (2025-08-19)
+
+
+### Features
+
+* add CLAUDE.md for Claude Code guidance ([#15](https://github.com/StackOneHQ/stackone-ai-python/issues/15)) ([ac9fe98](https://github.com/StackOneHQ/stackone-ai-python/commit/ac9fe9857f44c19394654dfcbe23fecc5cf9fbb0))
+* bring Python SDK to feature parity with Node SDK ([#17](https://github.com/StackOneHQ/stackone-ai-python/issues/17)) ([8b6de99](https://github.com/StackOneHQ/stackone-ai-python/commit/8b6de99184227cb7f1580964dc3eae14f8f60fc1))
+* remove automatic STACKONE_ACCOUNT_ID environment variable loading ([#23](https://github.com/StackOneHQ/stackone-ai-python/issues/23)) ([aa0aaf6](https://github.com/StackOneHQ/stackone-ai-python/commit/aa0aaf6d6bf528f8e29def9b008db23cf94b97c7))
+* simplify meta tool function names to match Node SDK ([#19](https://github.com/StackOneHQ/stackone-ai-python/issues/19)) ([4572609](https://github.com/StackOneHQ/stackone-ai-python/commit/4572609a9b85a88fc3067be12f821ec0bc54e769))
+
+
+### Miscellaneous Chores
+
+* release 0.3.0 ([#24](https://github.com/StackOneHQ/stackone-ai-python/issues/24)) ([beea911](https://github.com/StackOneHQ/stackone-ai-python/commit/beea91165ed2ba3eb5f5ad6ca8656344561b0b43))
+
 ## [0.0.4](https://github.com/StackOneHQ/stackone-ai-python/compare/stackone-ai-v0.0.3...stackone-ai-v0.0.4) (2025-03-05)
 
 

stackone_ai-0.3.1/CLAUDE.md

@@ -0,0 +1,120 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Cursor Rules
+
+- @./.cursor/rules/package-installation
+- @./.cursor/rules/no-relative-imports
+- @./.cursor/rules/uv-scripts
+- @./.cursor/rules/release-please-standards
+- @./.cursor/rules/examples-standards
+
+## 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
+
+```bash
+# Setup and installation
+make install           # Install dependencies and pre-commit hooks
+
+# Code quality
+make lint             # Run ruff linting
+make lint-fix         # Auto-fix linting issues  
+make mypy             # Run type checking
+
+# Testing
+make test             # Run all tests
+make test-tools       # Run tool-specific tests
+make test-examples    # Run example tests
+
+# Documentation
+make docs-serve       # Build and serve docs locally (http://localhost:8000)
+make docs-build       # Build docs for deployment
+
+# MCP Development
+make mcp-inspector    # Run MCP server inspector for debugging
+```
+
+## Code Architecture
+
+### Core Components
+
+1. **StackOneToolSet** (`stackone_ai/toolset.py`): Main entry point
+   - Handles authentication (API key + optional account ID)
+   - Manages tool loading with glob pattern filtering
+   - Provides format converters for OpenAI/LangChain
+
+2. **Models** (`stackone_ai/models.py`): Data structures
+   - `StackOneTool`: Base class with execution logic
+   - `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
+
+4. **MCP Server** (`stackone_ai/server.py`): Protocol implementation
+   - Async tool execution
+   - CLI interface via `stackmcp` command
+
+### 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_*"])
+```
+
+### Authentication
+```python
+# Uses environment variables or direct configuration
+toolset = StackOneToolSet(
+    api_key="your-api-key",  # or STACKONE_API_KEY env var
+    account_id="optional-id"  # explicit account ID required
+)
+```
+
+### Type Safety
+- Full type annotations required (Python 3.11+)
+- Strict mypy configuration
+- Use generics for better IDE support
+
+### Testing
+- Snapshot testing for tool parsing (`tests/snapshots/`)
+- Async tests use `pytest-asyncio`
+- Example validation: See @./.cursor/rules/examples-standards
+
+## Important Considerations
+
+1. **Dependencies**: See @./.cursor/rules/package-installation for uv dependency management
+2. **Pre-commit**: Hooks configured for ruff and mypy - run on all commits
+3. **Python Version**: Requires Python >=3.11
+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)
+
+## Common Tasks
+
+### Adding New SaaS Integration
+1. Add OpenAPI spec to `stackone_ai/oas/`
+2. Parser automatically converts to tool definitions
+3. Test with `make test-tools`
+
+### Modifying Tool Behavior
+- Core execution logic in `StackOneTool.execute()` method
+- HTTP configuration via `ExecuteConfig` class
+- Response handling in `_process_response()`
+
+### Updating Documentation
+- Examples requirements: See @./.cursor/rules/examples-standards
+- Run `make docs-serve` to preview changes
+- MkDocs config in `mkdocs.yml`

stackone_ai-0.3.1/PKG-INFO

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: stackone-ai
+Version: 0.3.1
+Summary: agents performing actions on your SaaS
+Author-email: StackOne <support@stackone.com>
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: bm25s>=0.2.2
+Requires-Dist: langchain-core>=0.1.0
+Requires-Dist: mcp[cli]>=1.3.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: pydantic>=2.10.6
+Requires-Dist: requests>=2.32.3
+Provides-Extra: docs
+Requires-Dist: mkdocs-terminal>=4.7.0; extra == 'docs'
+Requires-Dist: pygments>=2.12; extra == 'docs'
+Requires-Dist: pymdown-extensions; extra == 'docs'
+Provides-Extra: examples
+Requires-Dist: crewai>=0.102.0; extra == 'examples'
+Requires-Dist: langchain-openai>=0.3.6; extra == 'examples'
+Requires-Dist: openai>=1.63.2; extra == 'examples'
+Requires-Dist: python-dotenv>=1.0.1; extra == 'examples'
+Description-Content-Type: text/markdown
+
+# StackOne AI SDK
+
+[![PyPI version](https://badge.fury.io/py/stackone-ai.svg)](https://badge.fury.io/py/stackone-ai)
+[![GitHub release (latest by date)](https://img.shields.io/github/v/release/StackOneHQ/stackone-ai-python)](https://github.com/StackOneHQ/stackone-ai-python/releases)
+
+StackOne AI provides a unified interface for accessing various SaaS tools through AI-friendly APIs.
+
+## Features
+
+- Unified interface for multiple SaaS tools
+- AI-friendly tool descriptions and parameters
+- **Tool Calling**: Direct method calling with `tool.call()` for intuitive usage
+- **Glob Pattern Filtering**: Advanced tool filtering with patterns like `"hris_*"` and exclusions `"!hris_delete_*"`
+- **Meta Tools** (Beta): Dynamic tool discovery and execution based on natural language queries
+- Integration with popular AI frameworks:
+  - OpenAI Functions
+  - LangChain Tools
+  - CrewAI Tools
+  - LangGraph Tool Node
+
+## Installation
+
+```bash
+pip install stackone-ai
+```
+
+## Quick Start
+
+```python
+from stackone_ai import StackOneToolSet
+
+# Initialize with API key
+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.get_tools("hris_*", account_id="your-account-id")
+# Exclude certain tools with negative patterns
+tools = toolset.get_tools(["hris_*", "!hris_delete_*"])
+
+# Use a specific tool with the new call method
+employee_tool = tools.get_tool("hris_get_employee")
+# Call with keyword arguments
+employee = employee_tool.call(id="employee-id")
+# Or with traditional execute method
+employee = employee_tool.execute({"id": "employee-id"})
+```
+
+## Integration Examples
+
+<details>
+<summary>LangChain Integration</summary>
+
+StackOne tools work seamlessly with LangChain, enabling powerful AI agent workflows:
+
+```python
+from langchain_openai import ChatOpenAI
+from stackone_ai import StackOneToolSet
+
+# Initialize StackOne tools
+toolset = StackOneToolSet()
+tools = toolset.get_tools("hris_*", account_id="your-account-id")
+
+# Convert to LangChain format
+langchain_tools = tools.to_langchain()
+
+# Use with LangChain models
+model = ChatOpenAI(model="gpt-4o-mini")
+model_with_tools = model.bind_tools(langchain_tools)
+
+# Execute AI-driven tool calls
+response = model_with_tools.invoke("Get employee information for ID: emp123")
+
+# Handle tool calls
+for tool_call in response.tool_calls:
+    tool = tools.get_tool(tool_call["name"])
+    if tool:
+        result = tool.execute(tool_call["args"])
+        print(f"Result: {result}")
+```
+
+</details>
+
+<details>
+<summary>CrewAI Integration</summary>
+
+CrewAI uses LangChain tools natively, making integration seamless:
+
+```python
+from crewai import Agent, Crew, Task
+from stackone_ai import StackOneToolSet
+
+# Get tools and convert to LangChain format
+toolset = StackOneToolSet()
+tools = toolset.get_tools("hris_*", account_id="your-account-id")
+langchain_tools = tools.to_langchain()
+
+# Create CrewAI agent with StackOne tools
+agent = Agent(
+    role="HR Manager",
+    goal="Analyze employee data and generate insights",
+    backstory="Expert in HR analytics and employee management",
+    tools=langchain_tools,
+    llm="gpt-4o-mini"
+)
+
+# Define task and execute
+task = Task(
+    description="Find all employees in the engineering department",
+    agent=agent,
+    expected_output="List of engineering employees with their details"
+)
+
+crew = Crew(agents=[agent], tasks=[task])
+result = crew.kickoff()
+```
+
+</details>
+
+## Meta Tools (Beta)
+
+Meta tools enable dynamic tool discovery and execution without hardcoding tool names:
+
+```python
+# Get meta tools for dynamic discovery
+tools = toolset.get_tools("hris_*")
+meta_tools = tools.meta_tools()
+
+# Search for relevant tools using natural language
+filter_tool = meta_tools.get_tool("meta_search_tools")
+results = filter_tool.call(query="manage employees", limit=5)
+
+# Execute discovered tools dynamically
+execute_tool = meta_tools.get_tool("meta_execute_tool")
+result = execute_tool.call(toolName="hris_list_employees", params={"limit": 10})
+```
+
+## Examples
+
+For more examples, check out the [examples/](examples/) directory:
+
+- [Error Handling](examples/error_handling.py)
+- [StackOne Account IDs](examples/stackone_account_ids.py)
+- [Available Tools](examples/available_tools.py)
+- [File Uploads](examples/file_uploads.py)
+- [OpenAI Integration](examples/openai_integration.py)
+- [LangChain Integration](examples/langchain_integration.py)
+- [CrewAI Integration](examples/crewai_integration.py)
+- [LangGraph Tool Node](examples/langgraph_tool_node.py)
+- [Meta Tools](examples/meta_tools_example.py)
+
+## License
+
+Apache 2.0 License

stackone_ai-0.3.1/README.md

@@ -0,0 +1,154 @@
+# StackOne AI SDK
+
+[![PyPI version](https://badge.fury.io/py/stackone-ai.svg)](https://badge.fury.io/py/stackone-ai)
+[![GitHub release (latest by date)](https://img.shields.io/github/v/release/StackOneHQ/stackone-ai-python)](https://github.com/StackOneHQ/stackone-ai-python/releases)
+
+StackOne AI provides a unified interface for accessing various SaaS tools through AI-friendly APIs.
+
+## Features
+
+- Unified interface for multiple SaaS tools
+- AI-friendly tool descriptions and parameters
+- **Tool Calling**: Direct method calling with `tool.call()` for intuitive usage
+- **Glob Pattern Filtering**: Advanced tool filtering with patterns like `"hris_*"` and exclusions `"!hris_delete_*"`
+- **Meta Tools** (Beta): Dynamic tool discovery and execution based on natural language queries
+- Integration with popular AI frameworks:
+  - OpenAI Functions
+  - LangChain Tools
+  - CrewAI Tools
+  - LangGraph Tool Node
+
+## Installation
+
+```bash
+pip install stackone-ai
+```
+
+## Quick Start
+
+```python
+from stackone_ai import StackOneToolSet
+
+# Initialize with API key
+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.get_tools("hris_*", account_id="your-account-id")
+# Exclude certain tools with negative patterns
+tools = toolset.get_tools(["hris_*", "!hris_delete_*"])
+
+# Use a specific tool with the new call method
+employee_tool = tools.get_tool("hris_get_employee")
+# Call with keyword arguments
+employee = employee_tool.call(id="employee-id")
+# Or with traditional execute method
+employee = employee_tool.execute({"id": "employee-id"})
+```
+
+## Integration Examples
+
+<details>
+<summary>LangChain Integration</summary>
+
+StackOne tools work seamlessly with LangChain, enabling powerful AI agent workflows:
+
+```python
+from langchain_openai import ChatOpenAI
+from stackone_ai import StackOneToolSet
+
+# Initialize StackOne tools
+toolset = StackOneToolSet()
+tools = toolset.get_tools("hris_*", account_id="your-account-id")
+
+# Convert to LangChain format
+langchain_tools = tools.to_langchain()
+
+# Use with LangChain models
+model = ChatOpenAI(model="gpt-4o-mini")
+model_with_tools = model.bind_tools(langchain_tools)
+
+# Execute AI-driven tool calls
+response = model_with_tools.invoke("Get employee information for ID: emp123")
+
+# Handle tool calls
+for tool_call in response.tool_calls:
+    tool = tools.get_tool(tool_call["name"])
+    if tool:
+        result = tool.execute(tool_call["args"])
+        print(f"Result: {result}")
+```
+
+</details>
+
+<details>
+<summary>CrewAI Integration</summary>
+
+CrewAI uses LangChain tools natively, making integration seamless:
+
+```python
+from crewai import Agent, Crew, Task
+from stackone_ai import StackOneToolSet
+
+# Get tools and convert to LangChain format
+toolset = StackOneToolSet()
+tools = toolset.get_tools("hris_*", account_id="your-account-id")
+langchain_tools = tools.to_langchain()
+
+# Create CrewAI agent with StackOne tools
+agent = Agent(
+    role="HR Manager",
+    goal="Analyze employee data and generate insights",
+    backstory="Expert in HR analytics and employee management",
+    tools=langchain_tools,
+    llm="gpt-4o-mini"
+)
+
+# Define task and execute
+task = Task(
+    description="Find all employees in the engineering department",
+    agent=agent,
+    expected_output="List of engineering employees with their details"
+)
+
+crew = Crew(agents=[agent], tasks=[task])
+result = crew.kickoff()
+```
+
+</details>
+
+## Meta Tools (Beta)
+
+Meta tools enable dynamic tool discovery and execution without hardcoding tool names:
+
+```python
+# Get meta tools for dynamic discovery
+tools = toolset.get_tools("hris_*")
+meta_tools = tools.meta_tools()
+
+# Search for relevant tools using natural language
+filter_tool = meta_tools.get_tool("meta_search_tools")
+results = filter_tool.call(query="manage employees", limit=5)
+
+# Execute discovered tools dynamically
+execute_tool = meta_tools.get_tool("meta_execute_tool")
+result = execute_tool.call(toolName="hris_list_employees", params={"limit": 10})
+```
+
+## Examples
+
+For more examples, check out the [examples/](examples/) directory:
+
+- [Error Handling](examples/error_handling.py)
+- [StackOne Account IDs](examples/stackone_account_ids.py)
+- [Available Tools](examples/available_tools.py)
+- [File Uploads](examples/file_uploads.py)
+- [OpenAI Integration](examples/openai_integration.py)
+- [LangChain Integration](examples/langchain_integration.py)
+- [CrewAI Integration](examples/crewai_integration.py)
+- [LangGraph Tool Node](examples/langgraph_tool_node.py)
+- [Meta Tools](examples/meta_tools_example.py)
+
+## License
+
+Apache 2.0 License