/ 
Langertha-Knarr-1.102
/ Langertha::Knarr::Image

NAME

Langertha::Knarr::Image - Translate a client's image parts into Langertha::Content::Image objects

VERSION

version 1.102

SYNOPSIS

use Langertha::Knarr::Image;

# In a protocol's parse_chat_request:
my $messages = Langertha::Knarr::Image::openai_messages( $data->{messages} );

# Before a messages array is JSON-encoded for a trace or a log:
my $plain = Langertha::Knarr::Image::plain_messages($messages);

DESCRIPTION

Each client-facing protocol receives images in its own shape: OpenAI image_url content parts, Anthropic image blocks, Ollama's per-message images array of raw base64. The engine behind the route may speak another shape entirely. This module turns every face's image representation into Langertha::Content::Image objects inside the message content array; Langertha core then serializes them in the engine's own content_format (openai, anthropic, gemini, ollama, responses, lmstudio).

Translation needs a core whose Langertha::Content::Image serializes all of those formats (to_ollama, to_responses, to_lmstudio). On an older core (Langertha 0.503) the translators return the messages untouched and images keep passing through in the client's shape, as before.

Only messages that carry an image change. In such a message a bare { type => 'text', text => ... } part becomes a plain string, which core turns into the text part of whatever format the engine speaks; a text part with any other key (cache_control, ...) is kept as sent. The input arrays are never modified; a changed message is a copy.

An OpenAI image_url part's detail hint has no field on Langertha::Content::Image and is not carried.

translates

True when the installed core can serialize an image object into every engine content format, i.e. when this module translates at all.

content_formats

image_content_formats => Langertha::Knarr::Image::content_formats('openai', 'gemini'),

The engine content formats a protocol's images reach: every format when "translates", else the given formats that read the protocol's own shape untranslated.

openai_messages

anthropic_messages

ollama_messages

my $messages = Langertha::Knarr::Image::openai_messages( \@messages );

Returns a new ArrayRef of messages with the face's image representation replaced by Langertha::Content::Image objects, or the given ArrayRef itself when "translates" is false.

plain_messages

my $plain = Langertha::Knarr::Image::plain_messages($messages);

The messages with every image object replaced by its OpenAI image_url part (the URL as sent, or a data: URL; nothing is fetched), so a trace or request log can JSON-encode them. Returns the given ArrayRef when it holds no object.

SEE ALSO

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.