NAME
Langertha::Knarr::Handler - Role for Knarr backend handlers (Raider, Engine, Code, ...)
VERSION
version 1.001
SYNOPSIS
package My::Handler;
use Moose;
use Future;
with 'Langertha::Knarr::Handler';
sub handle_chat_f {
my ($self, $session, $request) = @_;
return Future->done({ content => 'hello', model => 'my-model' });
}
sub list_models { [ { id => 'my-model', object => 'model' } ] }
1;DESCRIPTION
The role every Knarr backend handler must consume. A handler is the "what answers the request" half of Knarr — it receives a normalized Langertha::Knarr::Request and returns either a sync result hash via "handle_chat_f" or an async chunk iterator via "handle_stream_f".
Knarr ships with concrete handlers for the common cases:
Langertha::Knarr::Handler::Code — coderef-backed, for tests/fakes
Langertha::Knarr::Handler::Engine — passthrough to a Langertha engine
Langertha::Knarr::Handler::Raider — per-session Langertha::Raider
Langertha::Knarr::Handler::Router — model-name routing via Langertha::Knarr::Router
Langertha::Knarr::Handler::Passthrough — raw HTTP forward to upstream
Langertha::Knarr::Handler::A2AClient — consume a remote A2A agent
Langertha::Knarr::Handler::ACPClient — consume a remote ACP agent
Langertha::Knarr::Handler::Tracing — Langfuse tracing decorator
Langertha::Knarr::Handler::RequestLog — JSONL request logging decorator
Decorators (Tracing, RequestLog) wrap an inner handler and themselves consume this role, so they compose freely.
handle_chat_f
my $future = $handler->handle_chat_f($session, $request);Required. Returns a Future that resolves to a hashref with at least a content key and optionally model.
handle_stream_f
my $stream = await $handler->handle_stream_f($session, $request);Default implementation calls "handle_chat_f" and emits the result as a single-chunk stream. Native streamers should override and return a Langertha::Knarr::Stream whose next_chunk_f yields chunk strings.
list_models
my $models = $handler->list_models;Required. Returns an arrayref of model descriptors as hashes with at least an id key.
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.