/ 
Langertha-0.303
River stage one • 1 direct dependent • 1 total dependent
/ Langertha::Role::Chat

NAME

Langertha::Role::Chat - Role for APIs with normal chat functionality

VERSION

version 0.303

SYNOPSIS

# Synchronous chat
my $response = $engine->simple_chat('Hello, how are you?');

# Streaming with callback
$engine->simple_chat_stream(sub {
    my ($chunk) = @_;
    print $chunk->content;
}, 'Tell me a story');

# Streaming with iterator
my $stream = $engine->simple_chat_stream_iterator('Tell me a story');
while (my $chunk = $stream->next) {
    print $chunk->content;
}

# Async with Future (traditional style)
my $future = $engine->simple_chat_f('Hello');
my $response = $future->get;

# Async with Future::AsyncAwait (recommended)
use Future::AsyncAwait;

async sub chat_example {
    my ($engine) = @_;
    my $response = await $engine->simple_chat_f('Hello');
    say $response;
}

# Async streaming with real-time callback
async sub stream_example {
    my ($engine) = @_;
    my ($content, $chunks) = await $engine->simple_chat_stream_realtime_f(
        sub { print shift->content },
        'Tell me a story'
    );
    say "\nTotal chunks: ", scalar @$chunks;
}

DESCRIPTION

This role provides chat functionality for LLM engines. It includes both synchronous and asynchronous (Future-based) methods for chat and streaming.

The Future-based _f methods are implemented using Future::AsyncAwait and Net::Async::HTTP. These modules are loaded lazily only when you call a _f method, so synchronous-only usage does not require them.

chat_model

The model name used for chat requests. Lazily defaults to default_chat_model if the engine provides it, otherwise falls back to the general model attribute from Langertha::Role::Models.

chat

my $request = $engine->chat(@messages);

Builds and returns a chat HTTP request object. Messages may be plain strings (treated as user role) or HashRefs with role and content keys. A system prompt from Langertha::Role::SystemPrompt is prepended automatically.

chat_messages

my $messages = $engine->chat_messages(@messages);

Normalises @messages into the canonical ArrayRef-of-HashRef format expected by chat_request. Plain strings become { role => 'user', content => $string }. If the engine has a system_prompt set it is prepended as a system message.

simple_chat

my $response = $engine->simple_chat(@messages);
my $response = $engine->simple_chat('Hello, how are you?');

Sends a synchronous chat request and returns the response text. Blocks until the request completes.

chat_stream

my $request = $engine->chat_stream(@messages);

Builds and returns a streaming chat HTTP request object. Croaks if the engine does not implement chat_stream_request. Use "simple_chat_stream" or "simple_chat_stream_iterator" to execute the request.

simple_chat_stream

my $content = $engine->simple_chat_stream($callback, @messages);

$engine->simple_chat_stream(sub {
    my ($chunk) = @_;
    print $chunk->content;
}, 'Tell me a story');

Sends a synchronous streaming chat request. Calls $callback with each Langertha::Stream::Chunk as it arrives. Returns the complete concatenated content string when done. Blocks until the stream completes.

simple_chat_stream_iterator

my $stream = $engine->simple_chat_stream_iterator(@messages);
while (my $chunk = $stream->next) {
    print $chunk->content;
}

Returns a Langertha::Stream iterator. The full response is fetched synchronously and buffered; iteration yields each Langertha::Stream::Chunk in order.

simple_chat_f

# Traditional Future style
my $response = $engine->simple_chat_f(@messages)->get;

# With async/await (recommended)
use Future::AsyncAwait;
async sub my_chat {
    my $response = await $engine->simple_chat_f(@messages);
    return $response;
}

Async version of "simple_chat". Returns a Future that resolves to the response text. Uses Net::Async::HTTP internally; loaded lazily on first call.

simple_chat_stream_f

my ($content, $chunks) = $engine->simple_chat_stream_f(@messages)->get;

Async streaming without a real-time callback. Convenience wrapper around "simple_chat_stream_realtime_f" with undef as the callback. Returns a Future that resolves to ($content, \@chunks).

simple_chat_stream_realtime_f

# With async/await (recommended)
use Future::AsyncAwait;
async sub my_stream {
    my ($content, $chunks) = await $engine->simple_chat_stream_realtime_f(
        sub { print shift->content },
        @messages
    );
    return $content;
}

# Traditional Future style
my $future = $engine->simple_chat_stream_realtime_f($callback, @messages);
my ($content, $chunks) = $future->get;

Async streaming with real-time callback. $callback is called with each Langertha::Stream::Chunk as it arrives from the server. Returns a Future that resolves to ($content, \@chunks) where $content is the full concatenated text.

This is the recommended method for real-time streaming in async applications. Pass undef as the callback (or use "simple_chat_stream_f") if you only need the final result.

SEE ALSO

SUPPORT

Issues

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

CONTRIBUTING

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

AUTHOR

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

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.