feat(stackone): add StackOne AI integration by ryoppippi · Pull Request #3 · StackOneHQ/pydantic-ai

ryoppippi · 2026-01-22T09:42:49Z

Summary

Add StackOne AI integration enabling AI agents to access 200+ SaaS integrations (HRIS, ATS, LMS, CRM, IAM, etc.) through a unified API.

Changes

Add tool_from_stackone() for individual tool integration
Add StackOneToolset for bulk registration with glob pattern filtering
Add comprehensive unit tests with 100% coverage
Add documentation and usage examples

New Files

pydantic_ai_slim/pydantic_ai/ext/stackone.py - Core integration module
tests/test_ext_stackone.py - Unit tests
examples/stackone_integration.py - Usage examples

Documentation Updates

docs/install.md - Added stackone extra
docs/third-party-tools.md - Added StackOne tools section
docs/toolsets.md - Added StackOne toolset section

Dependencies

stackone-ai>=2.1.1 (requires Python 3.10+, same as Pydantic AI)

Test plan

Unit tests pass (uv run pytest tests/test_ext_stackone.py)
StackOne-specific pyright check passes
Pre-commit checks pass (except existing upstream pyright issues unrelated to this PR)

Jira: ENG-10848

Add integration with StackOne unified API platform for HRIS, ATS, CRM, and other business systems. - Add `tool_from_stackone()` for single tool creation - Add `StackOneToolset` for bulk tool registration with pattern matching - Require stackone-ai>=2.1.1 (Python 3.10+) - Add documentation and examples - Add comprehensive unit tests with 100% coverage

- Fix StackOne URL from .co to .com - Update description to reflect current positioning as "AI Integration Gateway"

docs/toolsets.md

glebedel

We should update the examples but also add the meta tools! That would be a great value-add and differentiator for pydantic too because they might not have this concept at all.

eg. via import search_tool & execute_tool and that could take any tools, stackone tools for sure but also any other pydantic tools (eg. let's say the exa one)

examples/stackone_integration.py

docs/third-party-tools.md

Add search_tool, execute_tool, and feedback_tool functions that wrap StackOne's utility tools API (tool_search, tool_execute, tool_feedback). Extend StackOneToolset with new options: - include_utility_tools: enables dynamic tool discovery mode - include_feedback_tool: adds feedback collection capability - hybrid_alpha: configures BM25/TF-IDF search weight Update documentation and examples to reflect the new API.

Update minimum version requirement to 2.3.0 which includes the utility_tools API (tool_search, tool_execute, tool_feedback).

- Update StackOneToolset tests to match new implementation that uses _tool_from_stackone_tool directly instead of tool_from_stackone - Add test for include_utility_tools option - Mark docstring examples with test="skip" to avoid linting issues

- Remove `{test="skip"}` from docstring examples - Simplify StackOneToolset example to match ExaToolset pattern - Move Args documentation from class docstring to __init__ method - Remove verbose examples from search_tool, execute_tool, feedback_tool - Fix pyright type error in test file with ignore comment

- Replace hris_* with stackone_* in filter_pattern example - Replace hris_list_employees/hris_get_employee with stackone_* tools - Update description to remove 'unified interface' terminology

…_*/stackone_* Per PR review feedback, update all examples and tests to use actual StackOne provider naming patterns like 'bamboohr_*' and 'workday_*' instead of fictional 'hris_*' or 'stackone_*' patterns. - Update docs/toolsets.md examples - Update docs/third-party-tools.md examples - Update examples/stackone_integration.py - Update tests/test_ext_stackone.py - Update docstrings in pydantic_ai_slim/pydantic_ai/ext/stackone.py

- Format test file with ruff to fix line length issues - Add {test="skip"} to StackOneToolset docstring example to skip example test that requires stackone-ai package

Add stackone.py and test_ext_stackone.py to coverage omit list, similar to aci.py and exa.py which are also external integrations.

…lsets

shashi-stackone · 2026-02-24T10:17:41Z

Managed to get the CI passing now also noticed that in the Docs we are adding too many tools strategies there.

@glebedel Comparing to the others they just added how to use a toolset and multiple tools and thats's it .. having the Dynamic Discovery, Feedback and Search (semantic/lexical) would be great but we are adding too much on the page in the docs.

shashi-stackone

Made some changes to get CI and addressed some feedback

cubic-dev-ai

No issues found across 7 files

cubic-dev-ai

1 issue found across 3 files (changes from recent commits).

Prompt for AI agents (unresolved issues)


Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="pydantic_ai_slim/pydantic_ai/ext/stackone.py">

<violation number="1" location="pydantic_ai_slim/pydantic_ai/ext/stackone.py:16">
P2: According to linked Jira issue ENG-10848, the StackOne integration must expose the meta search/execute (& feedback) tools. This change removes those exports and the toolset no longer provides any path to include utility tools, so the requirement is no longer met.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

pydantic_ai_slim/pydantic_ai/ext/stackone.py

glebedel · 2026-03-10T10:14:42Z

docs/third-party-tools.md

+    search='auto',
+)
+
+agent = Agent('google-gla:gemini-2.5-flash', toolsets=[toolset])


I think our example should have a different model (better at tool calling), eg. haiku

Should gemimi-3 fine here? As I tested examples with Google API KEY?

glebedel · 2026-03-10T10:15:15Z

docs/third-party-tools.md

+from pydantic_ai.ext.stackone import StackOneToolset
+
+toolset = StackOneToolset(
+    search_query='list and manage employees',


does it make sense to do the search ahead of the agent call? Shouldn't it be more that the agent has search tool in the stackone toolset?

I think Pydantic AI toolsets define their tools at construction time and not sure it support dynamically adding tools during an agent run.. I will double check the source but pretty sure not

i'm not talking about adding tools during an agent run, i'm talking about having search & execute in the agent run.
What i don't understand here is why do you even have a search query? it's the agent/llm that should decide the query and use the search tool provided in agent declaration?

glebedel · 2026-03-10T10:16:56Z

tests/ext/test_stackone.py

+
+def test_tool_execution():
+    tool = stackone_ext._tool_from_stackone_tool(employee_tool)
+    result = tool.function(limit=10)  # type: ignore


do we need the # type: ignore here? is that best practice?

Added to make pyright happy on CI should be ok here for dynamically-created schema, removing cause type error .

glebedel · 2026-03-10T10:17:42Z

docs/third-party-tools.md

+)
+
+agent = Agent(
+    'google-gla:gemini-2.5-flash',


ditto on model

glebedel

not sure the search example makes sense

ryoppippi force-pushed the ENG-10848-try-to-get-listed-as-third-party-toolset-on-pydantic branch from d77e04f to 888b2d4 Compare January 22, 2026 11:26

ryoppippi changed the title ~~feat: add StackOne AI integration for Pydantic AI~~ feat(stackone): add StackOne AI integration Jan 22, 2026

docs(stackone): fix URL and update description

e369d07

- Fix StackOne URL from .co to .com - Update description to reflect current positioning as "AI Integration Gateway"

glebedel reviewed Jan 22, 2026

View reviewed changes

docs/toolsets.md Outdated Show resolved Hide resolved

glebedel reviewed Jan 22, 2026

View reviewed changes

docs/toolsets.md Outdated Show resolved Hide resolved

glebedel requested changes Jan 22, 2026

View reviewed changes

examples/stackone_integration.py Outdated Show resolved Hide resolved

docs/third-party-tools.md Show resolved Hide resolved

docs/third-party-tools.md Outdated Show resolved Hide resolved

ryoppippi added 8 commits January 30, 2026 15:30

chore(stackone): bump stackone-ai to >=2.3.0

1cb34c3

Update minimum version requirement to 2.3.0 which includes the utility_tools API (tool_search, tool_execute, tool_feedback).

chore(stackone): bump stackone-ai to >=2.3.1

24929da

chore: merge upstream/main and resolve uv.lock conflict

68653ea

fix(stackone): update docs/toolsets.md examples per review feedback

92c89dd

- Replace hris_* with stackone_* in filter_pattern example - Replace hris_list_employees/hris_get_employee with stackone_* tools - Update description to remove 'unified interface' terminology

ryoppippi requested a review from glebedel January 30, 2026 15:53

ryoppippi added 2 commits January 30, 2026 16:05

fix(stackone): fix CI lint and test failures

fd1225b

- Format test file with ruff to fix line length issues - Add {test="skip"} to StackOneToolset docstring example to skip example test that requires stackone-ai package

fix(stackone): exclude stackone files from coverage

e95b7e3

Add stackone.py and test_ext_stackone.py to coverage omit list, similar to aci.py and exa.py which are also external integrations.

glebedel requested a review from Shashikant86 February 3, 2026 11:31

shashi-stackone requested review from shashi-stackone and removed request for Shashikant86 February 23, 2026 16:03

shashi-stackone added 2 commits February 23, 2026 17:52

Apply further PR suggestions and fix CI

c6700e7

Remove stackone from extra dependency and follow same patter othe too…

a41f476

…lsets

shashi-stackone added the feature label Feb 23, 2026

shashi-stackone added 3 commits February 23, 2026 21:07

chore: retrigger CI after adding feature label to PR

da2358e

Skip the stackone coverage as its optional for toolset providers

6453f38

chore: retrigger CI

3585e04

shashi-stackone added 2 commits February 25, 2026 11:23

Remove the fedback tools from the Pydantic AI integration

f5f6526

update Pydantic example to use google gemini model as it tested locally

47f75a6

shashi-stackone added 2 commits February 26, 2026 09:24

chore: retrigger CI for cancelled job

27511c2

chore: retrigger CI for cancelled job

403c5d6

shashi-stackone approved these changes Feb 26, 2026

View reviewed changes

shashi-stackone marked this pull request as ready for review February 26, 2026 15:25

cubic-dev-ai bot reviewed Feb 26, 2026

View reviewed changes

Remove the utility tools from the Pydantic

dca5b53

cubic-dev-ai bot reviewed Feb 27, 2026

View reviewed changes

pydantic_ai_slim/pydantic_ai/ext/stackone.py Show resolved Hide resolved

shashi-stackone added 3 commits March 9, 2026 19:10

Update docs and include search

a8d4d23

Update docs with tool search and the include min similarity

580cea4

Fix Ruff issue

df805ee

glebedel reviewed Mar 10, 2026

View reviewed changes

docs/third-party-tools.md Outdated

)

agent = Agent(

'google-gla:gemini-2.5-flash',

Copy link
Copy Markdown

glebedel Mar 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ditto on model

glebedel reviewed Mar 10, 2026

View reviewed changes

update examples to use the google-gla:gemini-3-pro-preview model

ae117f0

Conversation

ryoppippi commented Jan 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

New Files

Documentation Updates

Dependencies

Test plan

Uh oh!

Uh oh!

Uh oh!

glebedel left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

shashi-stackone commented Feb 24, 2026

Uh oh!

shashi-stackone left a comment

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

glebedel Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

shashi-stackone Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

glebedel Mar 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shashi-stackone Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

glebedel Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

glebedel Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

shashi-stackone Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

glebedel Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

glebedel left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ryoppippi commented Jan 22, 2026 •

edited

Loading

glebedel Mar 10, 2026 •

edited

Loading