view release on metacpan or  search on metacpan

lib/Langertha/Knarr/Response.pm  view on Meta::CPAN

output that C<content> no longer holds — without it the reasoning is
lost at the proxy boundary. Recorded into the Langfuse generation
metadata; the protocol formatters currently do not emit it.

=head2 rate_limit

Optional L<Langertha::RateLimit> object built from the upstream
provider's quota headers. Kept as the object; consumers pull the
scalar fields they need.

=head2 raw

Optional. The provider-native response body, kept around for handlers
(passthrough-style) that want to preserve every byte upstream returned.

=head2 coerce

    my $r = Langertha::Knarr::Response->coerce( $whatever );

Class method. Accepts:

=over

=item * an existing C<Langertha::Knarr::Response> — returned as-is.

=item * a L<Langertha::Response> — fields lifted via
C<from_langertha_response>.

=item * any other blessed object that stringifies — used as C<content>.

=item * a HashRef — fed to C<new> after key normalization.

=item * a plain scalar — used as C<content>.

=item * C<undef> — produces an empty response.

=back

This is the single normalization entry point. Handlers can return
whatever shape is convenient and the dispatcher coerces once at the
boundary.

=head2 from_langertha_response

    my $r = Langertha::Knarr::Response->from_langertha_response($lresp);

Builds a Knarr response from a L<Langertha::Response>. Carries
C<content>, C<model>, C<usage>, C<tool_calls>, C<finish_reason>,
C<id>, C<timing>, C<thinking>, C<rate_limit>, and C<raw> across.
C<usage> arrives as the provider's raw HashRef and is upgraded to a
L<Langertha::Usage> on the way in; see L</usage>.

Every field is read behind a C<can()> guard so Knarr keeps working
against a L<Langertha> release that predates one of them — the older
attributes were added over several Langertha versions and C<timing> /
C<rate_limit> / C<thinking> are the most recent.

=head2 ttft_seconds

Time-to-first-token in seconds (Float) out of L</timing>, or C<undef>
when the engine did not measure it (non-streaming calls, or any handler
that is not engine-backed).

=head2 total_seconds

Total engine-measured call duration in seconds (Float) out of
L</timing>, or C<undef>.

=head2 has_tool_calls

True when C<tool_calls> contains at least one entry.

=head2 clone_with

    my $r2 = $r->clone_with( model => 'override' );

Returns a new response with the given fields overridden. All other
attributes carry through from C<$self>.

=head1 SUPPORT

=head2 Issues

Please report bugs and feature requests on GitHub at
L<https://github.com/Getty/langertha-knarr/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 <torsten@raudssus.de> L<https://raudssus.de/>

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus.

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