Add Chat Completions to Responses API migration guide

[TusharND12]

Summary

Adds examples/Migrate_from_chat_completions_to_responses.ipynb — a parameter-by-parameter guide for porting existing Chat Completions code to the Responses API.

Why

The Responses API is where new platform capabilities land, but this repo's own examples are still mostly written against Chat Completions:

	count
example notebooks with code cells	267
still calling chat.completions	97 (36%)
calling client.responses	40

The registry has six migration guides (Whisper → GPT-Transcribe, OpenAI Evals → Promptfoo, legacy codebase migration with sandbox agents, and others), but none for the migration most OpenAI developers actually face.

That gap matters because the port is not a find-and-replace. The traps are silent:

• Structured outputs change shape. Chat Completions nests the schema under a json_schema key; Responses hoists name/schema/strict to sit alongside type. Moving the object across unchanged fails validation. schema is also required in Responses where it was optional before.
• Tool definitions flatten the same way — the function wrapper disappears.
• output_text is empty whenever the model calls a tool. Per the SDK docstring: "If no output_text content blocks exist, then an empty string is returned." Code that assumes it is populated breaks the first time a tool fires.
• instructions does not carry across previous_response_id chains — a migrated system prompt silently stops applying on turn 2.
• Five parameters have no equivalent (n, seed, logit_bias, frequency_penalty, presence_penalty) and need rewrites, not renames.

Contents

Ten sections, each showing before/after side by side: the minimal migration, reading the output, the parameter map, instructions, multi-turn state, structured outputs, tools, streaming, reasoning models, and the parameters with no equivalent — closing with a migration checklist.

Section 3 derives the parameter map from the installed SDK at runtime by diffing Completions.create against Responses.create, rather than hardcoding a table. Readers verify against their own version, so the guide cannot silently go stale as the SDK moves.

Notes for reviewers

One deliberate departure from the docs. The migration guide lists verbosity as having no Responses equivalent, but the SDK exposes text.verbosity as Literal["low", "medium", "high"] (ResponseTextConfigParam). The notebook documents the SDK behavior. Happy to change it if the docs are the intended source of truth here.

Cells are not executed. The notebook ships without outputs, as several guide-style notebooks in the repo do (gpt-5/gpt-5-2_prompting_guide.ipynb, skills_in_api.ipynb, mcp/mcp_tool_guide.ipynb). Every cell is runnable; the code is illustrative and readers run it against their own key. I can execute and push outputs if you would prefer them.

Validation performed against openai 3.8.0:

• nbformat.validate passes; all 19 code cells parse
• every parameter in all 18 API calls checked against the real Completions.create / Responses.create signatures
• response attribute paths verified (usage.input_tokens, usage.output_tokens_details.reasoning_tokens, output_text as a property)
• .github/scripts/check_notebooks.py passes
• registry.yaml validates against .github/registry_schema.json; slug unique, path resolves

Sampling parameters are left out of the examples since reasoning models may reject them; the notebook notes this rather than demonstrating it.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 85205511d7

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[TusharND12]

Thanks for the review — pushed in c88afcb.

Applied as suggested:

• Lowercase filename — renamed to examples/migrate_from_chat_completions_to_responses.ipynb and updated the registry.yaml path to match the convention in AGENTS.md.
• OPENAI_API_KEY — named explicitly in the prerequisites with an export example, since every cell builds its client from that variable.
• Parity claim — qualified. The original wording did contradict the guide's own section 10, which is a fair catch.

On frequency_penalty / presence_penalty I kept the rows but made them precise rather than removing them, because I don't think they carry over. In openai 3.8.0:

"frequency_penalty" in inspect.signature(Responses.create).parameters  -> False
"frequency_penalty" in Response.model_fields                           -> False
Response.model_config["extra"]                                         -> "allow"

They aren't request parameters on responses.create, and aren't declared fields on Response. They show up in the saved response in examples/multimodal/image_evals.ipynb because extra="allow" lets any server-returned field pass through into the object — so frequency_penalty=0.0 there is an echoed default, not a setting the request honoured.

Rather than leave the original absolute wording, I changed it to state that they are "not accepted by responses.create" and added an explicit note that a Response may still echo them as defaults, so readers don't read that echo as support. Happy to drop the rows entirely if you'd prefer, but that would mean telling readers to keep passing a parameter the method doesn't accept.