stackone-ai 2.8.0__tar.gz → 2.9.0__tar.gz

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

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

{stackone_ai-2.8.0 → stackone_ai-2.9.0}/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [2.9.0](https://github.com/StackOneHQ/stackone-ai-python/compare/stackone-ai-v2.8.0...stackone-ai-v2.9.0) (2026-04-30)
+
+
+### Features
+
+* **integrations:** add native Pydantic AI support ([#184](https://github.com/StackOneHQ/stackone-ai-python/issues/184)) ([8216ab6](https://github.com/StackOneHQ/stackone-ai-python/commit/8216ab6c0776b0753cf3e68461bf5e8a9b044b06))
+
 ## [2.8.0](https://github.com/StackOneHQ/stackone-ai-python/compare/stackone-ai-v2.7.0...stackone-ai-v2.8.0) (2026-04-20)
 
 

{stackone_ai-2.8.0 → stackone_ai-2.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stackone-ai
-Version: 2.8.0
+Version: 2.9.0
 Summary: agents performing actions on your SaaS
 Author-email: StackOne <support@stackone.com>
 License-File: LICENSE
@@ -29,6 +29,8 @@ Requires-Dist: pydantic-ai>=1.83.0; extra == 'examples'
 Requires-Dist: python-dotenv>=1.0.1; extra == 'examples'
 Provides-Extra: mcp
 Requires-Dist: mcp>=1.3.0; extra == 'mcp'
+Provides-Extra: pydantic-ai
+Requires-Dist: pydantic-ai-slim<2.0.0,>=1.83.0; extra == 'pydantic-ai'
 Description-Content-Type: text/markdown
 
 # StackOne AI SDK
@@ -59,6 +61,7 @@ StackOne AI provides a unified interface for accessing various SaaS tools throug
   - LangChain Tools
   - CrewAI Tools
   - LangGraph Tool Node
+  - Pydantic AI Toolset
 
 ## Requirements
 
@@ -228,6 +231,43 @@ for tool_call in response.tool_calls:
 
 </details>
 
+<details>
+<summary>Pydantic AI Integration</summary>
+
+StackOne tools convert to Pydantic AI `Tool` instances via `.to_pydantic_ai()`, parallel to `.to_openai()` and `.to_langchain()`:
+
+Prerequisites:
+
+```bash
+pip install 'stackone-ai[pydantic-ai]'
+```
+
+```python
+import os
+from pydantic_ai import Agent
+from stackone_ai import StackOneToolSet
+
+toolset = StackOneToolSet()
+tools = toolset.fetch_tools(
+    actions=["workday_list_workers", "workday_get_worker"],
+    account_ids=[os.environ["STACKONE_ACCOUNT_ID"]],
+).to_pydantic_ai()
+
+agent = Agent("openai:gpt-5.4", tools=tools)
+result = agent.run_sync("List the first 5 employees")
+print(result.output)
+```
+
+For the full catalog (or the meta search/execute tools), use the `.pydantic_ai()` method on `StackOneToolSet` — parallel to `.openai()` / `.langchain()`:
+
+```python
+toolset = StackOneToolSet()
+tools = toolset.pydantic_ai(account_ids=[os.environ["STACKONE_ACCOUNT_ID"]])
+# or pydantic_ai(mode="search_and_execute") for agent-driven discovery
+```
+
+</details>
+
 <details>
 <summary>LangGraph Integration</summary>
 

{stackone_ai-2.8.0 → stackone_ai-2.9.0}/README.md

@@ -26,6 +26,7 @@ StackOne AI provides a unified interface for accessing various SaaS tools throug
   - LangChain Tools
   - CrewAI Tools
   - LangGraph Tool Node
+  - Pydantic AI Toolset
 
 ## Requirements
 
@@ -195,6 +196,43 @@ for tool_call in response.tool_calls:
 
 </details>
 
+<details>
+<summary>Pydantic AI Integration</summary>
+
+StackOne tools convert to Pydantic AI `Tool` instances via `.to_pydantic_ai()`, parallel to `.to_openai()` and `.to_langchain()`:
+
+Prerequisites:
+
+```bash
+pip install 'stackone-ai[pydantic-ai]'
+```
+
+```python
+import os
+from pydantic_ai import Agent
+from stackone_ai import StackOneToolSet
+
+toolset = StackOneToolSet()
+tools = toolset.fetch_tools(
+    actions=["workday_list_workers", "workday_get_worker"],
+    account_ids=[os.environ["STACKONE_ACCOUNT_ID"]],
+).to_pydantic_ai()
+
+agent = Agent("openai:gpt-5.4", tools=tools)
+result = agent.run_sync("List the first 5 employees")
+print(result.output)
+```
+
+For the full catalog (or the meta search/execute tools), use the `.pydantic_ai()` method on `StackOneToolSet` — parallel to `.openai()` / `.langchain()`:
+
+```python
+toolset = StackOneToolSet()
+tools = toolset.pydantic_ai(account_ids=[os.environ["STACKONE_ACCOUNT_ID"]])
+# or pydantic_ai(mode="search_and_execute") for agent-driven discovery
+```
+
+</details>
+
 <details>
 <summary>LangGraph Integration</summary>
 

{stackone_ai-2.8.0 → stackone_ai-2.9.0}/examples/pydantic_ai_integration.py

@@ -3,11 +3,13 @@
 ```bash
 uv run examples/pydantic_ai_integration.py
 ```
+
+Install with `pip install 'stackone-ai[pydantic-ai]'` (or
+`pip install 'stackone-ai[examples]'` to run this file).
 """
 
 from __future__ import annotations
 
-import json
 import os
 
 try:
@@ -18,31 +20,15 @@ except ModuleNotFoundError:
     pass
 
 try:
-    from pydantic_ai import Agent, Tool
+    from pydantic_ai import Agent
 except ImportError:
-    print("Install pydantic-ai to run this example: pip install pydantic-ai")
+    print("Install pydantic-ai to run this example: pip install 'stackone-ai[pydantic-ai]'")
     raise SystemExit(1) from None
 
 from stackone_ai import StackOneToolSet
 
 
-def _to_pydantic_ai_tool(stackone_tool) -> Tool:
-    """Convert a StackOneTool to a Pydantic AI Tool with the proper JSON schema."""
-    params_schema = stackone_tool.to_openai_function()["function"]["parameters"]
-
-    def execute(**kwargs: object) -> str:
-        return json.dumps(stackone_tool.execute(kwargs))
-
-    return Tool.from_schema(
-        execute,
-        name=stackone_tool.name,
-        description=stackone_tool.description,
-        json_schema=params_schema,
-    )
-
-
 def pydantic_ai_integration() -> None:
-    account_id = os.getenv("STACKONE_ACCOUNT_ID")
     for var in ["STACKONE_API_KEY", "STACKONE_ACCOUNT_ID", "OPENAI_API_KEY"]:
         if not os.getenv(var):
             print(f"Set {var} to run this example.")
@@ -51,12 +37,14 @@ def pydantic_ai_integration() -> None:
     toolset = StackOneToolSet()
     tools = toolset.fetch_tools(
         actions=["workday_list_workers", "workday_get_worker", "workday_get_current_user"],
-        account_ids=[account_id],
-    )
-    pydantic_tools = [_to_pydantic_ai_tool(t) for t in tools]
-    print(f"Loaded {len(pydantic_tools)} tools for Pydantic AI.")
+        account_ids=[os.environ["STACKONE_ACCOUNT_ID"]],
+    ).to_pydantic_ai()
 
-    agent = Agent("openai:gpt-5.4", system_prompt="You are a helpful HR assistant.", tools=pydantic_tools)
+    agent = Agent(
+        "openai:gpt-5.4",
+        system_prompt="You are a helpful HR assistant.",
+        tools=tools,
+    )
     result = agent.run_sync("List the first 5 employees")
     print(f"Result:\n{result.output}")
 

{stackone_ai-2.8.0 → stackone_ai-2.9.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "stackone-ai"
-version = "2.8.0"
+version = "2.9.0"
 description = "agents performing actions on your SaaS"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -37,6 +37,7 @@ packages = ["stackone_ai"]
 
 [project.optional-dependencies]
 mcp = ["mcp>=1.3.0"]
+pydantic-ai = ["pydantic-ai-slim>=1.83.0,<2.0.0"]
 examples = [
   "crewai>=0.102.0",
   "langchain-openai>=1.1.14",

{stackone_ai-2.8.0 → stackone_ai-2.9.0}/stackone_ai/__init__.py

@@ -23,4 +23,4 @@ __all__ = [
     "SemanticSearchResponse",
     "SemanticSearchError",
 ]
-__version__ = "2.8.0"
+__version__ = "2.9.0"

{stackone_ai-2.8.0 → stackone_ai-2.9.0}/stackone_ai/models.py

@@ -6,13 +6,16 @@ import logging
 from collections.abc import Sequence
 from datetime import datetime, timezone
 from enum import Enum
-from typing import Annotated, Any, ClassVar, TypeAlias, cast
+from typing import TYPE_CHECKING, Annotated, Any, ClassVar, TypeAlias, cast
 from urllib.parse import quote
 
 import httpx
 from langchain_core.tools import BaseTool
 from pydantic import BaseModel, BeforeValidator, Field, PrivateAttr
 
+if TYPE_CHECKING:
+    from pydantic_ai.tools import Tool as PydanticAITool
+
 # Type aliases for common types
 JsonDict: TypeAlias = dict[str, Any]
 Headers: TypeAlias = dict[str, str]
@@ -467,6 +470,36 @@ class StackOneTool(BaseModel):
 
         return StackOneLangChainTool()
 
+    def to_pydantic_ai_tool(self) -> PydanticAITool:
+        """Convert this tool to a Pydantic AI ``Tool``.
+
+        Requires ``stackone-ai[pydantic-ai]`` (installs ``pydantic-ai-slim``).
+
+        Returns:
+            A ``pydantic_ai.tools.Tool`` ready to pass to ``Agent(tools=[...])``.
+        """
+        try:
+            from pydantic_ai.tools import Tool
+        except ImportError as e:
+            raise ImportError(
+                "Install `pydantic-ai-slim` (or `stackone-ai[pydantic-ai]`) "
+                "to use the Pydantic AI integration."
+            ) from e
+
+        openai_function = self.to_openai_function()
+        json_schema = openai_function["function"]["parameters"]
+        parent_tool = self
+
+        def implementation(**kwargs: Any) -> Any:
+            return parent_tool.execute(kwargs)
+
+        return Tool.from_schema(
+            function=implementation,
+            name=self.name,
+            description=self.description,
+            json_schema=json_schema,
+        )
+
     def set_account_id(self, account_id: str | None) -> None:
         """Set the account ID for this tool
 
@@ -577,3 +610,13 @@ class Tools:
             Sequence of tools in LangChain format
         """
         return [tool.to_langchain() for tool in self.tools]
+
+    def to_pydantic_ai(self) -> list[PydanticAITool]:
+        """Convert all tools to Pydantic AI ``Tool`` instances.
+
+        Requires ``stackone-ai[pydantic-ai]`` (installs ``pydantic-ai-slim``).
+
+        Returns:
+            List of ``pydantic_ai.tools.Tool`` ready to pass to ``Agent(tools=[...])``.
+        """
+        return [tool.to_pydantic_ai_tool() for tool in self.tools]

{stackone_ai-2.8.0 → stackone_ai-2.9.0}/stackone_ai/toolset.py

@@ -11,7 +11,7 @@ import threading
 from collections.abc import Coroutine, Sequence
 from dataclasses import dataclass
 from importlib import metadata
-from typing import Any, Literal, TypedDict, TypeVar
+from typing import TYPE_CHECKING, Any, Literal, TypedDict, TypeVar
 
 from pydantic import BaseModel, Field, PrivateAttr, ValidationError, field_validator
 
@@ -32,6 +32,9 @@ from stackone_ai.semantic_search import (
 )
 from stackone_ai.utils.normalize import _normalize_action_name
 
+if TYPE_CHECKING:
+    from pydantic_ai.tools import Tool as PydanticAITool
+
 logger = logging.getLogger("stackone.tools")
 
 SearchMode = Literal["auto", "semantic", "local"]
@@ -752,6 +755,46 @@ class StackOneToolSet:
 
         return self.fetch_tools(account_ids=effective_account_ids).to_langchain()
 
+    def pydantic_ai(
+        self,
+        *,
+        mode: Literal["search_and_execute"] | None = None,
+        account_ids: list[str] | None = None,
+    ) -> list[PydanticAITool]:
+        """Get tools as Pydantic AI ``Tool`` instances.
+
+        Args:
+            mode: Tool mode.
+                ``None`` (default): fetch all tools and convert to Pydantic AI tools.
+                ``"search_and_execute"``: return two meta tools (tool_search + tool_execute)
+                that let the LLM discover and execute tools on-demand.
+            account_ids: Account IDs to scope tools. Overrides the ``execute``
+                config from the constructor.
+
+        Returns:
+            List of Pydantic AI ``Tool`` objects ready to pass to ``Agent(tools=...)``.
+
+        Requires ``stackone-ai[pydantic-ai]`` (installs ``pydantic-ai-slim``).
+
+        Examples::
+
+            # All tools
+            toolset = StackOneToolSet()
+            tools = toolset.pydantic_ai()
+            agent = Agent("openai:gpt-5.4", tools=tools)
+
+            # Meta tools for agent-driven discovery
+            tools = toolset.pydantic_ai(mode="search_and_execute")
+        """
+        effective_account_ids = account_ids or (
+            self._execute_config.get("account_ids") if self._execute_config else None
+        )
+
+        if mode == "search_and_execute":
+            return self._build_tools(account_ids=effective_account_ids).to_pydantic_ai()
+
+        return self.fetch_tools(account_ids=effective_account_ids).to_pydantic_ai()
+
     def execute(
         self,
         tool_name: str,

stackone_ai-2.9.0/tests/test_integrations_pydantic_ai.py

@@ -0,0 +1,183 @@
+"""Tests for the Pydantic AI integration."""
+
+from __future__ import annotations
+
+from typing import Any
+from unittest.mock import MagicMock
+
+import pytest
+
+pytest.importorskip("pydantic_ai", reason="pydantic-ai not installed")
+
+from pydantic_ai import Agent  # noqa: E402
+from pydantic_ai.tools import Tool  # noqa: E402
+
+from stackone_ai import StackOneToolSet  # noqa: E402
+from stackone_ai.models import ExecuteConfig, StackOneTool, ToolParameters, Tools  # noqa: E402
+
+
+@pytest.fixture
+def sample_tool() -> StackOneTool:
+    return StackOneTool(
+        description="List employees",
+        parameters=ToolParameters(
+            type="object",
+            properties={"limit": {"type": "integer", "description": "Max results"}},
+        ),
+        _execute_config=ExecuteConfig(
+            headers={},
+            method="GET",
+            url="https://api.example.com/employees",
+            name="bamboohr_list_employees",
+        ),
+        _api_key="test_key",
+    )
+
+
+@pytest.fixture
+def second_tool() -> StackOneTool:
+    return StackOneTool(
+        description="Get an employee",
+        parameters=ToolParameters(type="object", properties={}),
+        _execute_config=ExecuteConfig(
+            headers={},
+            method="GET",
+            url="https://api.example.com/employees/{id}",
+            name="bamboohr_get_employee",
+        ),
+        _api_key="test_key",
+    )
+
+
+# --- StackOneTool.to_pydantic_ai_tool() ---
+
+
+def test_tool_to_pydantic_ai_tool_returns_tool(sample_tool: StackOneTool):
+    tool = sample_tool.to_pydantic_ai_tool()
+    assert isinstance(tool, Tool)
+    assert tool.name == "bamboohr_list_employees"
+    assert tool.description == "List employees"
+
+
+def test_tool_to_pydantic_ai_tool_schema_matches_openai(sample_tool: StackOneTool):
+    tool = sample_tool.to_pydantic_ai_tool()
+    assert tool.function_schema.json_schema == sample_tool.to_openai_function()["function"]["parameters"]
+
+
+def test_tool_to_pydantic_ai_tool_executes_through_stackone(
+    sample_tool: StackOneTool, monkeypatch: pytest.MonkeyPatch
+):
+    captured: dict[str, Any] = {}
+
+    def fake_execute(self: StackOneTool, arguments: dict[str, Any]) -> Any:
+        captured["args"] = arguments
+        return {"ok": True}
+
+    monkeypatch.setattr(StackOneTool, "execute", fake_execute)
+
+    tool = sample_tool.to_pydantic_ai_tool()
+    result = tool.function(limit=10)  # type: ignore[operator]
+
+    assert captured["args"] == {"limit": 10}
+    assert result == {"ok": True}
+
+
+# --- Tools.to_pydantic_ai() ---
+
+
+def test_tools_to_pydantic_ai_converts_all(sample_tool: StackOneTool, second_tool: StackOneTool):
+    collection = Tools([sample_tool, second_tool])
+    tools = collection.to_pydantic_ai()
+
+    assert len(tools) == 2
+    assert [t.name for t in tools] == ["bamboohr_list_employees", "bamboohr_get_employee"]
+    assert all(isinstance(t, Tool) for t in tools)
+
+
+def test_tools_to_pydantic_ai_empty_collection():
+    collection = Tools([])
+    assert collection.to_pydantic_ai() == []
+
+
+def test_tools_to_pydantic_ai_with_agent(sample_tool: StackOneTool, monkeypatch: pytest.MonkeyPatch):
+    monkeypatch.setattr(StackOneTool, "execute", lambda self, arguments: {"employee_ids": ["1", "2"]})
+    tools = Tools([sample_tool]).to_pydantic_ai()
+
+    agent = Agent("test", tools=tools)
+    result = agent.run_sync("list employees")
+
+    assert "bamboohr_list_employees" in result.output
+
+
+# --- StackOneToolSet.pydantic_ai() ---
+
+
+def test_toolset_pydantic_ai_default_uses_fetch_tools(sample_tool: StackOneTool):
+    toolset = StackOneToolSet.__new__(StackOneToolSet)
+    toolset.fetch_tools = MagicMock(return_value=Tools([sample_tool]))  # type: ignore[method-assign]
+    toolset._build_tools = MagicMock()  # type: ignore[method-assign]
+    toolset._execute_config = None  # type: ignore[attr-defined]
+
+    tools = toolset.pydantic_ai()
+
+    toolset.fetch_tools.assert_called_once_with(account_ids=None)
+    toolset._build_tools.assert_not_called()
+    assert len(tools) == 1
+    assert tools[0].name == "bamboohr_list_employees"
+
+
+def test_toolset_pydantic_ai_search_and_execute_uses_build_tools(sample_tool: StackOneTool):
+    toolset = StackOneToolSet.__new__(StackOneToolSet)
+    toolset.fetch_tools = MagicMock()  # type: ignore[method-assign]
+    toolset._build_tools = MagicMock(return_value=Tools([sample_tool]))  # type: ignore[method-assign]
+    toolset._execute_config = None  # type: ignore[attr-defined]
+
+    tools = toolset.pydantic_ai(mode="search_and_execute")
+
+    toolset._build_tools.assert_called_once_with(account_ids=None)
+    toolset.fetch_tools.assert_not_called()
+    assert len(tools) == 1
+
+
+def test_toolset_pydantic_ai_account_ids_override(sample_tool: StackOneTool):
+    toolset = StackOneToolSet.__new__(StackOneToolSet)
+    toolset.fetch_tools = MagicMock(return_value=Tools([sample_tool]))  # type: ignore[method-assign]
+    toolset._build_tools = MagicMock()  # type: ignore[method-assign]
+    toolset._execute_config = {"account_ids": ["from-config"]}  # type: ignore[attr-defined]
+
+    toolset.pydantic_ai(account_ids=["override"])
+
+    toolset.fetch_tools.assert_called_once_with(account_ids=["override"])
+
+
+def test_toolset_pydantic_ai_falls_back_to_execute_config_account_ids(sample_tool: StackOneTool):
+    toolset = StackOneToolSet.__new__(StackOneToolSet)
+    toolset.fetch_tools = MagicMock(return_value=Tools([sample_tool]))  # type: ignore[method-assign]
+    toolset._build_tools = MagicMock()  # type: ignore[method-assign]
+    toolset._execute_config = {"account_ids": ["from-config"]}  # type: ignore[attr-defined]
+
+    toolset.pydantic_ai()
+
+    toolset.fetch_tools.assert_called_once_with(account_ids=["from-config"])
+
+
+# --- Import error path ---
+
+
+def test_to_pydantic_ai_tool_raises_helpful_import_error_when_package_missing(
+    sample_tool: StackOneTool, monkeypatch: pytest.MonkeyPatch
+):
+    """If `pydantic_ai` is not importable, the helper surfaces a clean install hint."""
+    import builtins
+
+    real_import = builtins.__import__
+
+    def fake_import(name: str, *args: Any, **kwargs: Any):
+        if name == "pydantic_ai.tools" or name.startswith("pydantic_ai"):
+            raise ImportError("No module named 'pydantic_ai'")
+        return real_import(name, *args, **kwargs)
+
+    monkeypatch.setattr(builtins, "__import__", fake_import)
+
+    with pytest.raises(ImportError, match="stackone-ai\\[pydantic-ai\\]"):
+        sample_tool.to_pydantic_ai_tool()

{stackone_ai-2.8.0 → stackone_ai-2.9.0}/uv.lock

@@ -4762,7 +4762,7 @@ wheels = [
 
 [[package]]
 name = "stackone-ai"
-version = "2.8.0"
+version = "2.9.0"
 source = { editable = "." }
 dependencies = [
     { name = "bm25s" },
@@ -4786,6 +4786,9 @@ examples = [
 mcp = [
     { name = "mcp" },
 ]
+pydantic-ai = [
+    { name = "pydantic-ai-slim" },
+]
 
 [package.dev-dependencies]
 dev = [
@@ -4813,10 +4816,11 @@ requires-dist = [
     { name = "openai", marker = "extra == 'examples'", specifier = ">=2.32.0" },
     { name = "pydantic", specifier = ">=2.10.6" },
     { name = "pydantic-ai", marker = "extra == 'examples'", specifier = ">=1.83.0" },
+    { name = "pydantic-ai-slim", marker = "extra == 'pydantic-ai'", specifier = ">=1.83.0,<2.0.0" },
     { name = "python-dotenv", marker = "extra == 'examples'", specifier = ">=1.0.1" },
     { name = "typing-extensions", specifier = ">=4.0.0" },
 ]
-provides-extras = ["mcp", "examples"]
+provides-extras = ["mcp", "pydantic-ai", "examples"]
 
 [package.metadata.requires-dev]
 dev = [

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

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