fallback_provider to model run #153

New issue

Closed

opened 2026-10-31 22:05:05 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-31 22:05:05 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/Comfy-Org/comfy-typescript-sdk/pull/150
Author: @deepme987
Created: 9/17/2026
Status: ✅ Merged
Merged: 9/18/2026
Merged by: @mattmillerai

Base: main ← Head: deepme987/router-provider-params

📝 Commits (7)

754eac7 chore: sync vendored Comfy Router spec from cloud@996a63c
b5e1a65 feat(models): add model_provider / strict_mode / fallback_provider to model run
002de57 test(models): add live Router alt-provider model-run e2e
3387914 fix(models): surface the alt-provider disclosure and stop two silent inversions
9e3e162 test(integration): require an explicit opt-in before the e2e tests bill
1837661 fix(retry): treat queue_timeout as terminal, and document the key's query identity
24a7fcb test(index): name the three new Router error classes at the package root

📊 Changes

16 files changed (+1230 additions, -116 deletions)

View changed files

📝 CHANGELOG.md (+19 -0)
📝 spec/router-openapi.yaml (+398 -35)
📝 src/index.test.ts (+8 -1)
📝 src/sdk/index.ts (+1 -1)
📝 src/sdk/modelRequests.ts (+16 -1)
➕ src/sdk/modelRoutes.test.ts (+74 -0)
📝 src/sdk/modelRoutes.ts (+80 -0)
📝 src/sdk/models.test.ts (+70 -1)
📝 src/sdk/models.ts (+147 -7)
📝 src/sdk/retry.test.ts (+8 -0)
📝 src/sdk/retry.ts (+8 -0)
📝 src/sdk/router-spec-contract.test.ts (+79 -43)
📝 src/sdk/routerErrors.test.ts (+20 -9)
📝 src/sdk/routerErrors.ts (+92 -18)
📝 src/sdk/surface-parity.test.ts (+16 -0)
➕ test/integration/router-models-e2e.test.ts (+194 -0)

📄 Description

What

Adds Comfy Router's three alt-provider controls to comfy.models.run, as optional RunOptions fields sent as query params on the synchronous run route (POST /v2/models/{provider}/{model}):

modelProvider (wire model_provider) — selects an alternate serving provider, e.g. "fal".
strictMode (wire strict_mode, rendered true/false) — false (default) translates between the model's native shape and the alternate provider both ways; true passes the provider's own raw shape unchanged in both directions.
fallbackProvider (wire fallback_provider) — "false" opts out of Router retrying against the model's other registered provider.

Each is built by routerRunQuery (in modelRoutes.ts) and emitted ONLY when the caller set it, in a fixed order. A run that names none appends no query at all, so it is byte-for-byte the request this route has always made.

Also reconciles the SDK with the vendored Router spec sync (cloud@996a63c) this branch is stacked on:

Types the three error buckets the contract now declares — cancelled, queue_timeout, request_not_found — as routerErrors.Cancelled / QueueTimeout / RequestNotFound (registered in BY_ERROR_TYPE, added to TRANSPORT_ERROR_TYPES). This is what the closed-set coverage gate (router-spec-coverage.test.ts) requires. They lead the Python SDK's table until its twin lands, declared in the surface-parity allowlist.
Pins the four queued model-request route constants against the spec now that the sync declares the requests collection (replacing the relation-only pin + its rot guard), and accounts for the four new operations in the route-coverage map.

Scope

Run route ONLY. The model_provider / strict_mode / fallback_provider params are not added to submit / subscribe / the queued RequestHandle — the backend does not accept them on the queue routes.

Testing

pnpm typecheck, pnpm lint, pnpm format:check, pnpm test (637 passed), pnpm build, and pnpm check:spec-drift all green locally.

New src/sdk/modelRoutes.test.ts covers routerRunQuery: empty when unset, per-field emission, strict_mode true/false, fixed order, and value encoding.
New wire assertions in models.test.ts prove the query reaches the request path only when set, and is absent otherwise.
routerErrors.test.ts / router-spec-coverage.test.ts cover the three new buckets end to end.

No live API calls.

Note

This branch is stacked on the auto-synced spec PR (#149, chore: sync vendored Comfy Router spec cloud@996a63c) — it includes that commit and supersedes it, so #149 can be closed in favor of this one. The spec sync should land first (or this merges it).

Companion PRs

Python: https://github.com/Comfy-Org/comfy-python-sdk/pull/159 (the reference implementation this mirrors)
Go: https://github.com/Comfy-Org/comfy-go-sdk/pull/5
Swift: https://github.com/Comfy-Org/comfy-swift-sdk/pull/80

Summary by CodeRabbit

New Features
- Added queued model execution with request submission, status polling, result retrieval, and cancellation.
- Added alternate-provider controls for synchronous model runs, including strict mode and fallback-provider selection.
- Added provider-selection details and translated-input reporting to model results.
- Added typed errors for cancelled requests, queue timeouts, and missing requests.
- Queue timeouts are now treated as terminal errors rather than retried.
Documentation
- Expanded the Router API specification with queue workflows, provider controls, response headers, and error behavior.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/Comfy-Org/comfy-typescript-sdk/pull/150 **Author:** [@deepme987](https://github.com/deepme987) **Created:** 9/17/2026 **Status:** ✅ Merged **Merged:** 9/18/2026 **Merged by:** [@mattmillerai](https://github.com/mattmillerai) **Base:** `main` ← **Head:** `deepme987/router-provider-params` --- ### 📝 Commits (7) - [`754eac7`](https://github.com/Comfy-Org/comfy-typescript-sdk/commit/754eac7fcdffcbae1cdf8cd3d279c34dc33b45ec) chore: sync vendored Comfy Router spec from cloud@996a63c - [`b5e1a65`](https://github.com/Comfy-Org/comfy-typescript-sdk/commit/b5e1a65fea73f4dd14443acfd1f88f7401fc1105) feat(models): add model_provider / strict_mode / fallback_provider to model run - [`002de57`](https://github.com/Comfy-Org/comfy-typescript-sdk/commit/002de5785e5e4938fbad5b1387106f330c421e94) test(models): add live Router alt-provider model-run e2e - [`3387914`](https://github.com/Comfy-Org/comfy-typescript-sdk/commit/33879149ccb30a2f465ac17301cecb01f2b9cdd3) fix(models): surface the alt-provider disclosure and stop two silent inversions - [`9e3e162`](https://github.com/Comfy-Org/comfy-typescript-sdk/commit/9e3e162460ad04eaedb51333eb29e16426680231) test(integration): require an explicit opt-in before the e2e tests bill - [`1837661`](https://github.com/Comfy-Org/comfy-typescript-sdk/commit/183766194bf9ad5d57ffb35ccd0b6db6c3f67b1c) fix(retry): treat queue_timeout as terminal, and document the key's query identity - [`24a7fcb`](https://github.com/Comfy-Org/comfy-typescript-sdk/commit/24a7fcb8dd2996ac4041493439c6bdc75af100cf) test(index): name the three new Router error classes at the package root ### 📊 Changes **16 files changed** (+1230 additions, -116 deletions) <details> <summary>View changed files</summary> 📝 `CHANGELOG.md` (+19 -0) 📝 `spec/router-openapi.yaml` (+398 -35) 📝 `src/index.test.ts` (+8 -1) 📝 `src/sdk/index.ts` (+1 -1) 📝 `src/sdk/modelRequests.ts` (+16 -1) ➕ `src/sdk/modelRoutes.test.ts` (+74 -0) 📝 `src/sdk/modelRoutes.ts` (+80 -0) 📝 `src/sdk/models.test.ts` (+70 -1) 📝 `src/sdk/models.ts` (+147 -7) 📝 `src/sdk/retry.test.ts` (+8 -0) 📝 `src/sdk/retry.ts` (+8 -0) 📝 `src/sdk/router-spec-contract.test.ts` (+79 -43) 📝 `src/sdk/routerErrors.test.ts` (+20 -9) 📝 `src/sdk/routerErrors.ts` (+92 -18) 📝 `src/sdk/surface-parity.test.ts` (+16 -0) ➕ `test/integration/router-models-e2e.test.ts` (+194 -0) </details> ### 📄 Description ## What Adds Comfy Router's three alt-provider controls to `comfy.models.run`, as optional `RunOptions` fields sent as query params on the synchronous run route (`POST /v2/models/{provider}/{model}`): - `modelProvider` (wire `model_provider`) — selects an alternate serving provider, e.g. `"fal"`. - `strictMode` (wire `strict_mode`, rendered `true`/`false`) — `false` (default) translates between the model's native shape and the alternate provider both ways; `true` passes the provider's own raw shape unchanged in both directions. - `fallbackProvider` (wire `fallback_provider`) — `"false"` opts out of Router retrying against the model's other registered provider. Each is built by `routerRunQuery` (in `modelRoutes.ts`) and emitted ONLY when the caller set it, in a fixed order. A run that names none appends no query at all, so it is byte-for-byte the request this route has always made. Also reconciles the SDK with the vendored Router spec sync (`cloud@996a63c`) this branch is stacked on: - Types the three error buckets the contract now declares — `cancelled`, `queue_timeout`, `request_not_found` — as `routerErrors.Cancelled` / `QueueTimeout` / `RequestNotFound` (registered in `BY_ERROR_TYPE`, added to `TRANSPORT_ERROR_TYPES`). This is what the closed-set coverage gate (`router-spec-coverage.test.ts`) requires. They lead the Python SDK's table until its twin lands, declared in the `surface-parity` allowlist. - Pins the four queued model-request route constants against the spec now that the sync declares the `requests` collection (replacing the relation-only pin + its rot guard), and accounts for the four new operations in the route-coverage map. ## Scope Run route ONLY. The `model_provider` / `strict_mode` / `fallback_provider` params are not added to `submit` / `subscribe` / the queued `RequestHandle` — the backend does not accept them on the queue routes. ## Testing `pnpm typecheck`, `pnpm lint`, `pnpm format:check`, `pnpm test` (637 passed), `pnpm build`, and `pnpm check:spec-drift` all green locally. - New `src/sdk/modelRoutes.test.ts` covers `routerRunQuery`: empty when unset, per-field emission, `strict_mode` `true`/`false`, fixed order, and value encoding. - New wire assertions in `models.test.ts` prove the query reaches the request path only when set, and is absent otherwise. - `routerErrors.test.ts` / `router-spec-coverage.test.ts` cover the three new buckets end to end. No live API calls. > [!NOTE] > This branch is stacked on the auto-synced spec PR (#149, `chore: sync vendored Comfy Router spec cloud@996a63c`) — it includes that commit and supersedes it, so #149 can be closed in favor of this one. The spec sync should land first (or this merges it). ## Companion PRs - Python: https://github.com/Comfy-Org/comfy-python-sdk/pull/159 (the reference implementation this mirrors) - Go: https://github.com/Comfy-Org/comfy-go-sdk/pull/5 - Swift: https://github.com/Comfy-Org/comfy-swift-sdk/pull/80  ## Summary by CodeRabbit - **New Features** - Added queued model execution with request submission, status polling, result retrieval, and cancellation. - Added alternate-provider controls for synchronous model runs, including strict mode and fallback-provider selection. - Added provider-selection details and translated-input reporting to model results. - Added typed errors for cancelled requests, queue timeouts, and missing requests. - Queue timeouts are now treated as terminal errors rather than retried. - **Documentation** - Expanded the Router API specification with queue workflows, provider controls, response headers, and error behavior.  --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-31 22:05:05 +00:00