/ 
Langertha-Knarr-1.001
/ Langertha::Knarr::Protocol

NAME

Langertha::Knarr::Protocol - Role for Knarr wire protocols (OpenAI, Anthropic, Ollama, A2A, ACP, AG-UI)

VERSION

version 1.001

DESCRIPTION

The role every Knarr wire protocol must consume. A protocol declares its routes, parses incoming HTTP bodies into a normalized Langertha::Knarr::Request, and formats outgoing Langertha::Knarr::Stream chunks back into the protocol-native wire format. The Knarr core dispatches each request to the right handler via the matched protocol's parser/formatter.

Knarr ships with six concrete protocols, all loaded by default:

protocol_name

Required. Returns a short string identifier (e.g. 'openai').

protocol_routes

Required. Returns an arrayref of route specs of the form { method => 'POST', path => '/v1/chat/completions', action => 'chat' }. Action names map to _action_* methods on the Knarr core.

parse_chat_request

my $req = $proto->parse_chat_request($http_request, \$body);

Required. Returns a Langertha::Knarr::Request.

format_chat_response

my ($status, \%headers, $body) = $proto->format_chat_response($response, $request);

Required. Returns the HTTP response triple for sync mode.

format_stream_open / format_stream_chunk / format_stream_close / format_stream_done

Lifecycle hooks for streaming responses. Defaults are no-ops where the protocol doesn't need framing — Anthropic/A2A/ACP/AG-UI override these to emit their named events around the chunk stream.

stream_content_type

Returns the HTTP Content-Type for streaming responses. Default text/event-stream; Ollama overrides to application/x-ndjson.

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.