view release on metacpan or  search on metacpan

lib/Langertha/Engine/OpenAIResponses.pm  view on Meta::CPAN

    use Langertha::Engine::OpenAIResponses;

    my $engine = Langertha::Engine::OpenAIResponses->new(
        api_key => $ENV{OPENAI_API_KEY},
        model   => 'gpt-5.5-pro',   # reasoning-only model
    );

    my $response = $engine->simple_chat('Hello');
    print $response;

=head1 DESCRIPTION

Provides access to OpenAI's Responses API endpoint (C<POST /v1/responses>)
for reasoning-only models like C<gpt-5.5-pro>, C<o3-pro>, and future
C<-pro> SKUs that are not available on the Chat Completions endpoint
(C</v1/chat/completions>).

Unlike L<Langertha::Engine::OpenAI> which calls C</v1/chat/completions>, this
engine calls C</v1/responses> with the Responses API's own request/response
shape. The Responses API uses:

=over 4

=item * C<input> instead of C<messages>

=item * C<instructions> for system prompt (top-level, not in input array)

=item * Flat tool objects C<{type, name, description, parameters}> instead
of C<{type, function, function: {...}}>

=item * C<output[]> array with type discriminators (C<message>, C<reasoning>,
C<function_call>) instead of C<choices[]>

=item * C<input_tokens>/C<output_tokens> instead of
C<prompt_tokens>/C<completion_tokens>

=item * C<output_tokens_details.reasoning_tokens> instead of
C<completion_tokens_details.reasoning_tokens>

=back

This engine returns a L<Langertha::Response> that is shape-compatible with
the chat path, so existing consumers (including Goldmine's C<complete>
method) work without modification. Reasoning tokens are normalized to
C<completion_tokens_details.reasoning_tokens> for cost lookup compatibility.

=head2 Function call output shape

The Responses API emits C<function_call> in two different positions
depending on model and request shape:

=over 4

=item * B<Top-level> C<output[]> item:
C<< { type =E<gt> 'function_call', call_id =E<gt> 'call_abc', name =E<gt> 'foo',
arguments =E<gt> '{...}' } >>. This is what real reasoning models (e.g.
C<gpt-5.5-pro>) return for forced C<tool_choice>.

=item * B<Nested> inside a message item:
C<< output[type='message'].content[type='function_call'] >>. Historically
seen in streaming / older fixtures.

=back

C<chat_response>, C<response_tool_calls> and L<Langertha::ToolCall/extract>
walk both shapes. Streaming is not supported.

=head1 SEE ALSO

=over

=item * L<Langertha::Engine::OpenAI> - Chat Completions endpoint (for non-reasoning models)

=item * L<Langertha::Role::OpenAICompatible> - OpenAI API format role

=item * L<Langertha::ToolCall> - Tool call extraction from Responses format

=item * L<Langertha::ToolChoice/to_responses> - Responses tool_choice serialization

=item * L<Langertha::Tool/to_responses> - Responses tool serialization

=back

=head1 SUPPORT

=head2 Issues

Please report bugs and feature requests on GitHub at
L<https://github.com/Getty/langertha/issues>.

=head2 IRC

Join C<#langertha> on C<irc.perl.org> or message Getty directly.

=head1 CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

=head1 AUTHOR

Torsten Raudssus <getty@cpan.org>

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus L<https://raudssus.de/>.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

=cut