refactor!: execute every tool over MCP tools/call, with session ids and submit_feedback()

Merged
WI
1mo ago
+14096-2272

refactor!: execute every tool over MCP tools/call, with session ids and submit_feedback()
main
Brings the Python SDK to parity with node #383. Every tool call goes over MCP tools/call, and GET /accounts is the only request outside MCP. The migration guide covers every breaking change since 2.10.1, including those from #199.

Changes

MCP-only execution

  • Per-action tools execute over tools/call on the endpoint and account that listed them, with the model's arguments sent unchanged. The server maps them itself.
  • Removed:
    • the /actions/rpc client;
    • the envelope splitting;
    • the base httpx executor;
    • binary download handling and filename cleanup;
    • the param-style=flat_prefixed pin.
  • A tool returns the server's result exactly as the server wrote it: {isError: false, result, defenderMetadata?, policyMetadata?} for action tools, bare JSON for search. isError still raises StackOneAPIError with the status from its payload.
  • A file action returns UCA's single-use download link as result, or raises with status 501 when no link can be issued.
  • tools/call is now sent without the mcp client's extra tools/list. Its output-schema check relisted the whole catalog before every call, and the Node SDK never did that.
  • The transport uses streamable_http_client; the deprecated streamablehttp_client warned on every call.

Header arguments

  • A header argument is an entry of a nested headers object or a top-level headers_<name>. Each is forwarded only if the served schema declares it in the same form. An open headers object (no properties, as *_execute_action serves it) declares every name.
  • Authorization, x-account-id and User-Agent are never forwarded. The warning says whether a header was undeclared or set by the SDK. Every other argument is sent unchanged.
  • As a result, toolset.execute() now forwards host-set headers through the open headers object.

Feedback and sessions

  • stackone_submit_feedback goes over tools/call only, and is listed once however many accounts serve it.
  • submit_feedback() lists one account in search_execute mode and makes one tools/call, through the lowest account id in scope (not the first given, nor GET /accounts order). It takes an optional action_run_id, sent only when given.
  • The search session_id is on every hit, and is forwarded by execute(..., session_id=) and submit_feedback(). A pinned action_id / session_id is moved to the end of the arguments.

Matches Node exactly

  • The served required is emitted verbatim and in the served order, and an empty one is omitted.
  • A tools/call result with only structuredContent is returned instead of coming back as {}.
  • Tools.get_tool() returns the first tool listed under a duplicated name, like Node's getTool().
  • The test mock serves schemas verbatim from a low-level MCP Server. The old one listed properties: {} for every per-action tool.

Also

  • FeedbackRating, FeedbackCategory, FeedbackSource and StackOneMcpTool are exported from stackone_ai. submit_feedback(tool_names=) takes any sequence of strings, but not a bare str.
  • The base StackOneTool no longer requires _api_key.
  • A PR-title check mirrors the Node SDK's.

Review fixes

  • A 429 is retried only when the wait ends before the request's deadline: the MCP exchange's timeout, or the toolset timeout from the first attempt for GET /accounts. Otherwise the 429 is raised at once, so a multi-account call can't time out a throttled account into a partial catalog.
  • An MCP timeout says "timed out after Ns" instead of "RuntimeError: no running event loop".
  • Nested header values are written as Node's headerText writes them (true, 1, compact JSON). Header names are trimmed as JavaScript's trim() trims them.
  • Unusable arguments raise the new ToolArgumentsError, a StackOneError and a ValueError. ToolParameters.required is declared. An account id that is not a string is rejected. An account list fetched across clear_catalog_cache() is discarded. A Retry-After date that overflows falls back to the backoff.

Second review round (decided once with node #383 and sdk-conformance)

  • KeyboardInterrupt and SystemExit propagate out of an MCP request; only Exception becomes a ToolsetLoadError.
  • The langchain extra requires langchain-core>=0.3.36, the first that takes a dict args_schema.
  • A root type that is not a string, such as ["object", "null"], is read as "object", as Node does, instead of "['object', 'null']".
  • A timeout on a request retried after a 429 is that 429 (StackOneAPIError 429, fatal to a multi-account call), on MCP and GET /accounts, worded as Node words it.
  • Non-text content parts (image, audio, resource) are returned under content_parts as plain JSON, so json.dumps and execute_openai_tool_calls() work.
  • Search hits carry the account_id that found them; top_k limits the merged, globally sorted list; the same action on two accounts is two hits.
  • execute() raises ToolsetConfigError when the action's connector is linked on more than one account in scope; a hit's account_id in account_ids routes to it.
  • to_openai(), to_langchain() and to_pydantic_ai() keep the first tool of each name (the lowest account id) and warn once.
  • When some accounts fail to list, the healthy accounts' listings are cached and a failed account is retried only after FAILED_ACCOUNT_RETRY_SECONDS (30). When every account fails, the shared StackOneAPIError is raised if they all have one status, else a ToolsetLoadError raised from an ExceptionGroup of the failures, which it also keeps in .failures.
  • Constructing a toolset with no account while STACKONE_ACCOUNT_ID is set warns that it is ignored.
  • Every GET /accounts (discovery or fetch_accounts()) records the origin_username of each account with shared: false, and every MCP request for that account carries it as x-end-user-id, set after caller headers. Explicit account ids make no GET /accounts. A model-supplied x-end-user-id header argument is dropped as set by the SDK.
  • Tests pin the partial-failure caching, the move of a pinned session_id to the end in execute() and the SDK-owned-name filter on headers= in _prepare_headers; each fails under its mutation.

CI: the conformance pin moves to sdk-conformance ec4dcfb (StackOneHQ/sdk-conformance#5), which grades all of the above, and the conformance job now runs the full suite with the Node SDK (NODE_SDK_REF, refactor/mcp-only-toolset until node #383 merges) beside this one.

Verification

  • 815 tests pass; ruff check, ruff format --check and ty (package and examples) are clean, and uv lock --locked passes. The MIGRATION.md hand-built-tool recipe passes ty and pyright.
  • tests/vectors/ is byte-identical to sdk-conformance 7347926, the pinned commit, and every shared vector case passes.
  • The full conformance suite at 7347926 (pnpm test -- --strict-schema, both SDKs, with Node at c2b8736) passes: 139 checks, and all 68 scenarios give identical results in Python and Node, warnings included. CI runs the same full suite against a pinned Node commit.
  • The override block below was run through release-please 17.11.2's parseConventionalCommits: 45 entries, 23 breaking, each BREAKING CHANGE note on its own entry and none on the others, no junk entries, and next version 3.0.0 from 2.10.1. It covers #199's breaking changes too, except the removal of StackOneTool.connector and Tools.get_connectors(), which #199's own squash commit already carries as a BREAKING CHANGE footer.

BEGIN_COMMIT_OVERRIDE
refactor: execute every tool over MCP tools/call

BREAKING CHANGE: StackOneRpcTool, MCP_PARAM_STYLE, ParameterLocation, validate_method, is_json_content_type and filename_from_content_disposition are removed. Every tool fetch_tools() returns is a StackOneMcpTool that executes over MCP tools/call on the endpoint and account that listed it, with its arguments sent unchanged; nothing posts to /actions/rpc.

refactor(tools): remove the HTTP executor from the base StackOneTool

BREAKING CHANGE: StackOneTool.execute() no longer makes HTTP requests. On the base class it raises StackOneError, so a hand-built tool must override execute().

refactor(types): reduce ExecuteConfig to name, headers and timeout

BREAKING CHANGE: ExecuteConfig is extra="forbid" and keeps only name, headers and timeout. Passing method, url, body_type or parameter_locations raises a pydantic ValidationError.

refactor(toolset): return every result exactly as the server wrote it

BREAKING CHANGE: StackOneToolSet.execute() and tool.execute() return the server's {isError, result, defenderMetadata?, policyMetadata?} object rather than the unwrapped payload or the /actions/rpc body, so result["data"] becomes result["result"]["data"].

refactor(tools): return a download link from file actions

BREAKING CHANGE: a file action returns {download_url, expires_at, file} as result instead of {content, content_type, status_code, headers, file_name}, and raises StackOneAPIError with status 501 when no link can be issued. Tools.execute_openai_tool_calls() no longer base64-encodes bytes.

refactor(toolset): stop pinning param-style=flat_prefixed on the MCP endpoint

BREAKING CHANGE: the /mcp URL no longer carries ?param-style=flat_prefixed, so per-action tools from fetch_tools() take whichever argument style the server serves by default instead of flat, prefixed keys such as body_variables.

refactor(tools): treat StackOneMcpTool headers as extra headers

BREAKING CHANGE: StackOneMcpTool(headers=...) is now optional and means extra request headers, not the full header set. The SDK always sets Authorization, x-account-id and User-Agent itself, after them.

fix(tools): emit the served required list in served order

BREAKING CHANGE: to_openai_function() no longer derives required from the per-property nullable markers. It emits the served root required list verbatim, in the served order, and omits it when absent or empty, so a hand-built ToolParameters without required now has no required fields.

fix(toolset): route stackone_submit_feedback over MCP and list it once

BREAKING CHANGE: fetch_tools(), openai(), langchain() and pydantic_ai() include the stackone_submit_feedback tool, once, whenever the server serves it.

fix(tools): guard every header argument by its own declaration

BREAKING CHANGE: a top-level headers_<name> argument is dropped unless the tool's schema declares that property, and always for Authorization, x-account-id and User-Agent. A declared flat headers_<name> property no longer admits the same name inside a nested headers object. An open headers object, as *_execute_action serves it, forwards any other header, so StackOneToolSet.execute(..., {"headers": {...}}) passes host-set headers through where it previously dropped them all. A top-level headers argument that isn't a plain object is dropped too, unless the schema declares headers itself as a non-object field, in which case it is an ordinary argument sent as given. A declared flat headers_<name> argument whose value is a list or dict is dropped as well; only a string, number or boolean can be a header value.

fix(tools): return the first listing from get_tool(), as Node does

BREAKING CHANGE: when more than one account serves a tool name, Tools.get_tool() returns the first one listed (listings merge in sorted account order) rather than the last.

build: require Python 3.11 or later

BREAKING CHANGE: Python 3.10 is no longer supported. stackone-ai requires Python 3.11 or later.

build: make mcp a core dependency and remove the mcp extra

BREAKING CHANGE: the stackone-ai[mcp] extra no longer exists. mcp is a core dependency, so install plain stackone-ai.

build: make langchain-core an optional dependency

BREAKING CHANGE: langchain-core is no longer installed with stackone-ai. StackOneTool.to_langchain(), Tools.to_langchain() and StackOneToolSet.langchain() need the stackone-ai[langchain] extra, which requires langchain-core 0.3.36 or later, and raise an ImportError that names it without it.

refactor: split stackone_ai.models into stackone_ai.tools and stackone_ai.types

BREAKING CHANGE: stackone_ai.models, stackone_ai.constants and stackone_ai.utils no longer exist. Import StackOneTool and Tools from stackone_ai.tools; ToolParameters, ExecuteConfig, DEFAULT_BASE_URL and the errors from stackone_ai.types; or any public name from stackone_ai. ToolDefinition and DEFAULT_HYBRID_ALPHA are removed.

refactor(toolset): remove client-side search

BREAKING CHANGE: client-side search is removed: SearchConfig, SearchMode, SearchTool, SemanticSearchClient, SemanticSearchResult, SemanticSearchResponse and SemanticSearchError, the search= constructor argument, search_tools(), search_action_names(), get_search_tool(), semantic_client, the tool_search and tool_execute meta tools, and the bm25s and numpy dependencies. StackOneToolSet.search() runs the server's *_search_actions tools instead.

refactor: remove stackone_ai.integrations

BREAKING CHANGE: stackone_ai.integrations, with to_tool_node(), to_tool_executor(), bind_model_with_tools() and create_react_agent(), is removed. Pass tools.to_langchain() to LangGraph's own ToolNode and bind_tools().

refactor(tools): remove the client-side feedback tool

BREAKING CHANGE: the tool_feedback tool, stackone_ai.feedback, create_feedback_tool() and the implicit feedback_* execution options are removed, and StackOneTool.execute() and call() no longer take options=. Use StackOneToolSet.submit_feedback() and a search hit's session_id instead.

refactor(toolset): run an action by id with execute()

BREAKING CHANGE: StackOneToolSet.execute() takes (action_id, arguments=None, *, account_ids=None, session_id=None) instead of a meta tool name with arguments as a JSON string or dict. arguments must be a dict in the nested form an action's example_request shows, and a failure raises (ToolsetConfigError, ToolArgumentsError, ToolsetLoadError or StackOneAPIError) instead of returning {"error": ...}.

refactor(tools): pass the served schema through to every adapter

BREAKING CHANGE: to_openai_function(), to_langchain() and to_pydantic_ai_tool() give the model the served JSON Schema instead of only type, description, enum and a shallow copy of items and properties, so format, pattern, default, bounds, oneOf/anyOf and nested required reach it. to_langchain() sets that schema as args_schema instead of a pydantic model built from it.

refactor(toolset): remove mode= from openai(), langchain() and pydantic_ai()

BREAKING CHANGE: openai(), langchain() and pydantic_ai() no longer take mode=. Set tool_mode="search_execute" on StackOneToolSet to give a model the server's search and execute tools.

fix(toolset): reject an empty or non-string account id

BREAKING CHANGE: StackOneToolSet(account_id="") raises ToolsetConfigError instead of being treated as no account, which now lists every active account, so an account id read from an environment variable that is set but empty raises. An empty or non-string entry in account_ids, set_accounts() or execute={"account_ids": [...]} raises too, instead of being sent with no x-account-id.

feat(toolset): link calls with session_id and add submit_feedback()

fix(toolset): send feedback once, through the first account

fix(toolset): move a pinned action_id and session_id to the end of the arguments

fix(tools): return structuredContent from a tools/call result with no text

fix(tools): send tools/call without relisting the catalog first

feat: export the feedback types and StackOneMcpTool, and take any sequence of tool names

refactor(tools): make the base StackOneTool's API key optional

feat: retry HTTP 429 on every request, honouring Retry-After, and raise a 429 that outlasts the retries or the timeout instead of skipping the account

feat(tools): raise ToolArgumentsError, a StackOneError and a ValueError, for unusable tool arguments

fix(types): declare ToolParameters.required so a hand-built tool type-checks

fix(tools): write nested header values as Node writes them

fix(tools): report an MCP timeout as a timeout

feat(toolset): read STACKONE_BASE_URL

fix(toolset): accept account ids only as a list

BREAKING CHANGE: account_ids, set_accounts() and execute={"account_ids": ...} accept only a list of strings. A tuple or any other non-list, which 2.10.1 accepted, raises ToolsetConfigError; pass list(ids) instead.

feat(toolset): tag each search hit with its account_id and apply top_k to the merged ranking

fix(toolset): refuse an action whose connector is linked on more than one account

fix(tools): build every adapter from the first tool of each name

fix(toolset): cache the healthy accounts when one fails, and retry a failed one after 30 seconds

fix(toolset): raise the shared error when every account fails, and keep each failure

feat(toolset): add action_run_id to submit_feedback(), and send feedback through the lowest account id

feat(toolset): warn when STACKONE_ACCOUNT_ID is set but ignored

feat(toolset): send x-end-user-id for non-shared accounts

feat(toolset): add a headers option sent on every request

feat(toolset): skip non-shared accounts during discovery unless include_non_shared

fix(toolset): refuse to execute while a matching account failed to list

fix(toolset): look up a non-shared account's end user when the API asks for it

fix(toolset): re-list only the failed accounts that could serve the action in execute()

fix(toolset): learn a failed account's provider with one GET /accounts before execute() refuses

fix(toolset): chain a failed end-user lookup onto the 400 it was looking up for

fix(toolset): raise when every active account on the key is non-shared and not opted in

fix(toolset): name shared accounts in the STACKONE_ACCOUNT_ID warning

fix(tools): keep a retried 429 on record while another request in the exchange is answered

A timeout on a tools/list retried after a 429 is reported as that 429, even when another request in the MCP exchange is answered meanwhile, rather than as a plain timeout that skips the account.

fix(toolset): hold a provider lookup's miss for the failed-account window in execute()

When GET /accounts fails to name a failed account, execute() neither looks it up again nor lists it again early for 30 seconds, and still refuses with the cached failure.
END_COMMIT_OVERRIDE


Summary by cubic

Brings the Python SDK to parity with the Node SDK (#383): every tool now executes over MCP tools/call on the endpoint and account that listed it, with GET /accounts the only non-MCP request. This is the 3.0 release; MIGRATION.md (linked from README, shipped in the sdist) covers every change since 2.10.1.

Behavior changes

  • Tools return the server's result verbatim; a no-text result falls back to structuredContent, non-text parts come back as plain JSON, and isError raises StackOneAPIError. Adapters emit the served required list verbatim and in order.
  • File actions return the download link or raise 501; download filenames are reduced exactly as Node's TextDecoder does. NaN, Infinity, and unencodable arguments raise ToolArgumentsError; JSON integers above 2^53 keep their exact value.
  • tools/call goes through send_request over streamable_http_client, buffering the server's error body on failure; MCP timeouts are reported as timeouts and KeyboardInterrupt/SystemExit propagate. A call never relists the catalog first.
  • Only HTTP 429 is retried (up to three), honoring Retry-After as seconds or a strict RFC 9110 HTTP-date (capped at 30s, else jittered backoff); a retry that would overrun the deadline is skipped and a 429 that outlasts retries aborts the call. Failed accounts retry after 30s; when every account fails, the shared StackOneAPIError is raised if they all share one status, else a ToolsetLoadError raised from an ExceptionGroup kept in .failures. Concurrent fetch_tools()/search() share one in-flight GET /accounts.
  • Header arguments are forwarded only when the schema declares them; Authorization, x-account-id, User-Agent, and x-end-user-id never are. A non-object headers argument is dropped unless the schema declares headers itself as an ordinary field; a flat list/dict header or a self-referential value is refused. A toolset-level headers= option goes on every request; non-shared accounts carry an x-end-user-id.
  • Base URL resolves argument → STACKONE_BASE_URL → default, and a set-but-unused STACKONE_ACCOUNT_ID warns.
  • submit_feedback() is served over tools/call only, in every mode, listed once regardless of how many accounts serve it, and goes through the lowest account id in scope with an optional action_run_id. Search hits carry session_id and account_id; top_k limits the merged ranking; execute(..., session_id=) forwards the hit's session id. An action linked on more than one account raises unless a hit's account_id routes it.
  • New exports: FeedbackRating, FeedbackCategory, FeedbackSource, StackOneMcpTool, ToolArgumentsError. fetch_tools(tool_names=...) accepts any sequence; the langchain extra requires langchain-core>=0.3.36.
  • CI pins sdk-conformance, runs the full suite against this and the Node SDK side by side, vendors shared test vectors byte-for-byte, and adds a PR-title check. The mock serves per-action schemas verbatim from a low-level MCP Server.

Breaking changes

  • Removed StackOneRpcTool, MCP_PARAM_STYLE, ParameterLocation, validate_method, is_json_content_type, and filename_from_content_disposition. StackOneTool.execute() no longer makes HTTP requests; the base class raises StackOneError and _api_key is optional.
  • ExecuteConfig keeps only name, headers, timeout; other fields raise ValidationError. Action results are the server's {isError, result, ...} object; downloads return a link, not bytes.
  • An empty or non-string account id, or a non-list account_ids, raises ToolsetConfigError. A top-level headers_<name> argument is dropped unless declared; with duplicate tool names, get_tool(), to_openai(), to_langchain(), and to_pydantic_ai() return the first listing.
  • Python 3.11 or later is required, and mcp is now a core dependency (the stackone-ai[mcp] extra is gone).