/ 
Langertha-Knarr-1.100
/ Langertha::Knarr::Response

NAME

Langertha::Knarr::Response - Normalized chat response shared across all Knarr handlers and protocol formatters

VERSION

version 1.100

DESCRIPTION

The single shape every Langertha::Knarr::Handler returns and every Langertha::Knarr::Protocol formatter consumes. Mirrors Langertha::Response but is decoupled from it so non-engine handlers (Langertha::Knarr::Handler::Code, Langertha::Knarr::Handler::A2AClient, Langertha::Knarr::Handler::ACPClient) can produce a Knarr response without going through Langertha first.

BUILDARGS upgrades all the legacy shapes Knarr handlers used to return — a bare string, a { content => ..., model => ... } hashref, or a stringifiable Langertha::Response — into a proper value object. So existing call sites can pass anything they already had and downstream code can rely on a single API.

content

Plain assistant text. Defaults to empty string.

model

The model id that produced the response, if known.

usage

A Langertha::Usage object with token counts, if the engine reported them. undef for handlers that have no usage data (Code, Passthrough).

tool_calls

ArrayRef of Langertha::ToolCall objects produced by the engine. Empty arrayref when the response is plain text.

finish_reason

Provider-agnostic stop reason (stop, tool_calls, length, ...). Optional; the protocol formatters fall back to stop / end_turn when undef.

raw

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

coerce

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

Class method. Accepts:

  • an existing Langertha::Knarr::Response — returned as-is.

  • a Langertha::Response — fields lifted via from_langertha_response.

  • any other blessed object that stringifies — used as content.

  • a HashRef — fed to new after key normalization.

  • a plain scalar — used as content.

  • undef — produces an empty response.

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

from_langertha_response

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

Builds a Knarr response from a Langertha::Response. Carries content, model, usage, tool_calls, finish_reason, and raw across.

has_tool_calls

True when tool_calls contains at least one entry.

clone_with

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

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

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/langertha-knarr/issues.

IRC

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

CONTRIBUTING

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

AUTHOR

Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/

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.