Implement Assistants to Responses API migration

[joacir]

Motivation

The OpenAI Assistants beta API is scheduled to shut down on August 26, 2026 in favor of the Responses + Conversations stack (official migration guide). This PR brings full SDK support for the new stack so users can migrate before the sunset.

What's added (25 new public methods, 4 new URL helpers)

Responses API (/v1/responses)

response() with streaming callback support, retrieveResponse(), deleteResponse(), cancelResponse(), listResponseInputItems().

response() follows the same ($opts, $stream = null) signature as chat() / completion() so existing streaming patterns transfer over.

Conversations API (/v1/conversations)

createConversation(), retrieveConversation(), modifyConversation(), deleteConversation(), createConversationItems(), listConversationItems(), retrieveConversationItem(), deleteConversationItem(). Used as the stateful replacement for Threads.

Vector Stores API (/v1/vector_stores)

16 methods covering stores (createVectorStore, searchVectorStore, …), files (createVectorStoreFile, updateVectorStoreFileAttributes, …) and file batches (createVectorStoreFileBatch, …). Required for the file_search tool in Responses.

Prompts API (/v1/prompts)

retrievePrompt() for dashboard-managed prompt templates that can be referenced from response() via prompt => ['id' => 'pmpt_…'].

What's deprecated

All 28 methods in the Assistants/Threads/Messages/Runs/RunSteps families (createAssistant, createThread, createThreadMessage, createRun, submitToolOutputs, retrieveRunStep, etc.) get an @deprecated PHPDoc tag pointing at the new replacement method. No behavior change — they keep working until OpenAI shuts them down.

The README has a deprecation banner with a legacy→new mapping table at the top of the Assistants beta section.

Bug fixes

1. chat() and response() now correctly throw 'Please provide a stream function…' when stream => true is passed without a callback. Previously the missing callback fell through to sendRequest() and triggered a fatal Typed property OpenAi::$stream_method must not be accessed before initialization. The fix mirrors the existing — and correct — logic already in completion().

2. The pre-existing should handle simple chat completion using the new endpoint test was asserting on the obsolete "text" key; updated to "object": "chat.completion" + "content" to match the current Chat Completions response shape.

Compatibility

• No new dependencies. Pure ext-curl + ext-json like the rest of the SDK.
• PHP 7.4 preserved. No 8.0+ syntax introduced.
• No breaking changes. All existing public methods keep their signatures; only PHPDoc deprecation tags added.
• setBaseURL / setCustomURL continue to work for Azure OpenAI / self-hosted gateways — the new methods all route through the existing baseUrl($url) rewrite.
• No new HTTP headers required. Responses / Conversations / Vector Stores / Prompts are all GA and don't need the OpenAI-Beta header.

Test plan

12 new tests added to the working group covering create / retrieve / list / delete / stream-throw across the new families. All 13 (including the updated chat assertion) pass against the live OpenAI API:

$ vendor/bin/pest --filter="response|conversation|vector store|stream true without callback|simple chat completion using the new"
…
Tests:  13 passed
Time:   25.16s

Additional verification:

• php -l clean on src/Url.php, src/OpenAi.php, tests/OpenAiTest.php
• vendor/bin/php-cs-fixer fix --dry-run --allow-risky=yes reports zero changes needed
• Cherry-picked cleanly on top of current main (4ba9c70)
• No conflict with the recent addAssistantsBetaHeader() refactor

Files

File	Change
src/Url.php	+36 lines (4 new helpers: responsesUrl, conversationsUrl, vectorStoresUrl, promptsUrl)
src/OpenAi.php	+442 / -3 (25 new methods, 28 @deprecated tags, 2 bug fixes)
tests/OpenAiTest.php	+139 / -1 (12 new tests + updated chat assertion)
README.md	+263 (new sections for Responses, Conversations, Vector Stores, Prompts + deprecation banner + migration table)

Happy to address feedback or split into multiple PRs if preferred.