Add support for Responses API

[momostafa]

What:

• New Feature

Adds the new feature Responses API: https://platform.openai.com/docs/api-reference/responses

OpenAI's most advanced interface for generating model responses. Supports text and image inputs, and text outputs. Create stateful interactions with the model, using the output of previous responses as input. Extend the model's capabilities with built-in tools for file search, web search, computer use, and more. Allow the model access to external systems and data using function calling.

---

Fixes: #535
Laravel PR: openai-php/laravel#147

[iBotPeaches]

I started going through this, but it doesn't really follow the pattern at all :/

Some top level comments

• Place the Contract into src/Contracts/Resources
• Drop the Transporter/Payload iterations - you can reuse that logic.
• Move the Response API into src/Resources
• Split the Response/Resource into src/Resources & src/Responses
• Introduce some heavy tests.

[momostafa]

Thanks for reviewing the PR, I will go over it again and let you know

[iBotPeaches]

Can you run some of the tooling locally? Without tests and the bar having to be at 100% and some linting errors - this has a bit further to go.

composer test:lint
composer test:types
composer test:unit
composer test:type-coverage min=100

I put them in order of complexity.

[momostafa]

Can you run some of the tooling locally? Without tests and the bar having to be at 100% and some linting errors - this has a bit further to go.

composer test:lint
composer test:types
composer test:unit
composer test:type-coverage min=100

I put them in order of complexity.

Please find attached test results, sorry I don't have time to fix all errors. Phpstan already gave me a lot of headaches.

test:unit.txt
test:types.txt
test:type-coverage min=100.txt
test:lint.txt

[momostafa]

@iBotPeaches Please check my last commit 412f35c

with above commit I tested live all models and all are working.
sorry but I don't have time to go further if there are anything needed to be changed etc...
I hope someone else can carry on from where i finished.

Thank you for your understanding

[iBotPeaches]

@momostafa - thanks for your work so far. I triggered the pipeline so you can see the failures right now. I'll look for some time if you've tapped out to take this further.

[momostafa]

@momostafa - thanks for your work so far. I triggered the pipeline so you can see the failures right now. I'll look for some time if you've tapped out to take this further.

You are welcome and thank you for your time looking into my PR. I am seriously overloaded but since there only 2 fails I will work on it tonight and I will get back to you.

[momostafa]

@momostafa - thanks for your work so far. I triggered the pipeline so you can see the failures right now. I'll look for some time if you've tapped out to take this further.

Hi, Now test:lint pass on my local machine please check momostafa@29436e8
Thank you

[momostafa]

@momostafa - thanks for your work so far. I triggered the pipeline so you can see the failures right now. I'll look for some time if you've tapped out to take this further.

Sorry... I will check the other failing

[momostafa]

dd263ac
@iBotPeaches I have ran all tests several times and all passed 100% please check.
Thank you

[iBotPeaches]

Getting closer! A few things here and there, but the major aspect I see missing is the tests. You produced some fixtures, but nothing to assert any of the work you did - works.

• You'll need a Resource test, ie like Assistants
• You'll need a Response test for all types of responses, ie like Assistants
• Finally, a simple test to assert the mocking/pass-through all works with a more full body Response test - ie w/ Assistants again

[momostafa]

Getting closer! A few things here and there, but the major aspect I see missing is the tests. You produced some fixtures, but nothing to assert any of the work you did - works.

• You'll need a Resource test, ie like Assistants
• You'll need a Response test for all types of responses, ie like Assistants
• Finally, a simple test to assert the mocking/pass-through all works with a more full body Response test - ie w/ Assistants again

Yeah getting closer : ) thank you for your patience and detailed inputs on what's needs to be fixed. I will try to resolve it today

[iBotPeaches]

Yeah getting closer : ) thank you for your patience and detailed inputs on what's needs to be fixed. I will try to resolve it today

No worries, I'm excited to get this as well. Thanks for continuing to work on it. I know this is a big new endpoint, which I'll probably migrate all my Chat endpoints towards once completed.

[elnurvl]

@momostafa , thank you for this great contribution! I am also looking forward to see this merged.

Question: Does the documentation in the description reflect the current state of this PR?

In your readme file this can be found:

// Example: Stream a response
$stream = $responses->createStreamed([
    'model' => 'gpt-4o',
    'input' => [ // Changed to input to match implementation, assuming input is not a valid parameter
        [
            'content' => 'The quick brown fox jumps over the lazy fox.',
        ],
    ],
]);

According to the Responses API specification, content receives an array of inputs(e.g. text, file), not a plain string:

curl "https://api.openai.com/v1/responses" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
        "model": "gpt-4o",
        "input": [
            {
                "role": "user",
                "content": [
                    {
                        "type": "input_file",
                        "filename": "draconomicon.pdf",
                        "file_data": "...base64 encoded PDF bytes here..."
                    },
                    {
                        "type": "input_text",
                        "text": "What is the first dragon in the book?"
                    }
                ]
            }
        ]
    }'

Also, it is also not mentioned, what would be the implied role if it is not given in input. user?

Updating the repository README file as part of this PR would be very helpful.

[momostafa]

@momostafa , thank you for this great contribution! I am also looking forward to see this merged.

Question: Does the documentation in the description reflect the current state of this PR?

In your readme file this can be found:

// Example: Stream a response
$stream = $responses->createStreamed([
    'model' => 'gpt-4o',
    'input' => [ // Changed to input to match implementation, assuming input is not a valid parameter
        [
            'content' => 'The quick brown fox jumps over the lazy fox.',
        ],
    ],
]);

According to the Responses API specification, content receives an array of inputs(e.g. text, file), not a plain string:

curl "https://api.openai.com/v1/responses" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
        "model": "gpt-4o",
        "input": [
            {
                "role": "user",
                "content": [
                    {
                        "type": "input_file",
                        "filename": "draconomicon.pdf",
                        "file_data": "...base64 encoded PDF bytes here..."
                    },
                    {
                        "type": "input_text",
                        "text": "What is the first dragon in the book?"
                    }
                ]
            }
        ]
    }'

Also, it is also not mentioned, what would be the implied role if it is not given in input. user?

Updating the repository README file as part of this PR would be very helpful.

You are most welcome, I am glad to be able to make a small contribution to the community. Sorry for the delay since last update as it was quite a challenge to pass Pest tests as finally I found that fake function at Fakeable trait.
$class = str_replace('Responses\', 'Testing\Responses\Fixtures\', static::class).'Fixture';
was conflicting with the newly created folder Responses and I had to modify the function please see full details at the docblock on top of fake function OpenAI\Testing\Responses\Concerns\Fakeable::fake

I have submitted a review and I hope it will pass this time.

Thank you
I

[momostafa]

@iBotPeaches Hi, Please check last commit caf4413

• Test:lint passed
• Test:types passed
• Test:type-coverage min=100 passed
• Test:unit 12 failed that I can't solve

Please review and I appreciate if you can fix what is left so we can all benefit of using the Response API.

Thank you for your understanding and guidance through the process.

[iBotPeaches]

Had a bit more time before bed. Notes:

• Streaming needs some work - everything is parsing to same class. The structure changes if the event is output_item, content_part, output_text, function_call, file_search_call, refusal, etc
• stream tests are encoding the array directly. They should be moved into the respective Fixture file

[momostafa]

@momostafa - just some thoughts in case you want to take them for learning. I knocked out a chunk of work - probably another day or two to finalize this.

• No need for the complex logic you had for the Responses/* collision. We know that wasn't perfect so expanding that to `OpenAI//Responses//* allows it to be scoped to the right part and not collide with our new folder.
• You had the tests/mocking for $metadata, but did not collect/parse it.
• You had Pest assertions off raw arrays, which doesn't work. You'd have to wrap the entire array in an expect() clause for that to work. For now I'm removing that and will go back and augment the assertions based on the array.
• Functions sometimes just included wrong thing - i.e a stream function returning a payload, or a stream getting an array - just looked like some confusion

Thank you, for your time fixing what is needed and your inputs certainly a good learning curve for me. The whole streaming thing was very confusing for me as well as the multiple tests, testing folders... was driving me crazy : )))

[iBotPeaches]

Thank you, for your time fixing what is needed and your inputs certainly a good learning curve for me. The whole streaming thing was very confusing for me as well as the multiple tests, testing folders... was driving me crazy : )))

No worries. I very much need this feature too so will get this done. I think you got a bit confused as you hit arrays/objects, which is why the tests weren't working well. Generally anytime you are typing an array/object - that suggests you need to make a class that represents that data structure. I'm basically going down the list and fixing any array/object.

• See usage converted into objects here - 18bf40e
• See error converted into objects here - e9d3d95

Hopefully those examples help explain the changes.

[momostafa]

Thank you, for your time fixing what is needed and your inputs certainly a good learning curve for me. The whole streaming thing was very confusing for me as well as the multiple tests, testing folders... was driving me crazy : )))

No worries. I very much need this feature too so will get this done. I think you got a bit confused as you hit arrays/objects, which is why the tests weren't working well. Generally anytime you are typing an array/object - that suggests you need to make a class that represents that data structure. I'm basically going down the list and fixing any array/object.

• See usage converted into objects here - 18bf40e
• See error converted into objects here - e9d3d95

Hopefully those examples help explain the changes.

Thanks for pointing out at such patterns I was totally away from coding for 6+ years and just got back about 7 month ago and I am still catching up with all PHP changes as well as learning about Laravel for the first time. Besides that PHP is totally neglected by AI providers and we don't have the leverage of having a PHP SDK (like Python & TypeScript) that would eliminate a lot of confusion and guess work...!

[iBotPeaches]

Thanks for pointing out at such patterns I was totally away from coding for 6+ years and just got back about 7 month ago and I am still catching up with all PHP changes as well as learning about Laravel for the first time. Besides that PHP is totally neglected by AI providers and we don't have the leverage of having a PHP SDK (like Python & TypeScript) that would eliminate a lot of confusion and guess work...!

No worries. Glad you started the PR - its always hard to start such a large task with nothing so I'm happy I got work from a base. I'm working on the outputs chunk which is a pain in the butt.

Which is basically an array of output messages (5 different types) and some of those types are massively large.

[momostafa]

Thanks for pointing out at such patterns I was totally away from coding for 6+ years and just got back about 7 month ago and I am still catching up with all PHP changes as well as learning about Laravel for the first time. Besides that PHP is totally neglected by AI providers and we don't have the leverage of having a PHP SDK (like Python & TypeScript) that would eliminate a lot of confusion and guess work...!

No worries. Glad you started the PR - its always hard to start such a large task with nothing so I'm happy I got work from a base. I'm working on the outputs chunk which is a pain in the butt.

Which is basically an array of output messages (5 different types) and some of those types are massively large.

Woow sorry, I didn't know that I had to split the output into several classes like that... I could have followed this path if you had instructed me earlier

[iBotPeaches]

This is going to be a large large pr. Making my way through it. I didn't fully understand the scope of the Responses API until I sat down and dove into it. It has support for everything (reasoning, tool call, computer calling, file searching, function call, regular text) on top of custom tools and formats.

If I had to summarize remaining work:

• fully type the tools array
• meld all docblock changes from child classes into main Create, Retrieve and List
• copy changes over to retrieve/list
• increase coverage to 100%, by adding the tests I previously removed that were trying to assert on an array

With Easter near, will lose a few days of time, but otherwise I'm hoping to get this all done & merged before April is over.