compatcompatSign in
OpenAI

OpenAI SDK migration

Move between Chat Completions and Responses, retire model ids, and update tools and streaming without guessing.

Try compat freeSee a real pull request

1 repository · 3 migrations a month · no card

What compat detects

  • openai
  • @ai-sdk/openai
  • openai-edge

Two API surfaces coexist in the OpenAI Node SDK, and majors move parameters between them. compat maps messages to input, functions to tools, response_format to text.format, and replaces retired model ids only with ids named in the release notes or your instruction.

What breaks across majors

  1. 01

    Chat Completions (chat.completions.create) versus Responses (responses.create): request shape and output access differ.

  2. 02

    Model deprecations: retired ids appear in code, env defaults and tests.

  3. 03

    Streaming event types differ between the two surfaces.

  4. 04

    functions became tools with type: 'function'; response_format became text.format on Responses.

  5. 05

    Error classes and client options such as maxRetries and timeout moved between majors.

Request and response types are generated, so typecheck catches most surface migrations. Tests usually mock the client and need the new response shapes.

What an openai v4 to v5 run looks like

Illustrative

compat inventories every openai import and model id, plans the surface migration file by file, edits the request and response access, regenerates the lockfile, re-runs your checks and opens the pull request with the remaining manual steps, typically the model ids you must choose yourself. Illustrative; no public run recorded yet.

  1. 01

    Detect

    compat finds the OpenAI packages your code imports and the upstream releases that affect them.

  2. 02

    Migrate and verify

    It edits only the affected code in a disposable sandbox, regenerates the lockfile, and runs your existing tests, type checks, lint and build where available.

  3. 03

    Pull request

    It opens a PR with the diff, verification results, warnings and manual steps. A person merges.

Questions

Does compat merge the OpenAI migration automatically?
No. compat has no merge capability. It pushes a branch and opens a pull request with the diff, the recorded checks and any manual steps. A person on your team reviews and merges.
Which checks run?
Your repository's own: install, typecheck, lint, test and build where the scripts exist. Each is listed in the pull request as passed, failed or not run. A check that did not run is never shown as passed.
Does compat need my production credentials?
No. Migrations run in a disposable sandbox with your code and package manager, not your environment. Checks that need live credentials are reported as not run.
How does compat know a release affects my repository?
It watches the OpenAI packages your code imports, reads new release notes, and judges relevance against the files that actually use the SDK. Irrelevant releases are dismissed with the reason; relevant ones become a proposal or, if you allow it, a run.
Will compat pick a replacement model for me?
No. It replaces retired ids only with ids named in the documentation or your instruction, and lists any open choice as a manual step.

Other providers