/ 
Langertha-0.302
River stage zero No dependents
/ Langertha::Plugin

NAME

Langertha::Plugin - Base class for plugins

VERSION

version 0.302

SYNOPSIS

package Langertha::Plugin::MyPlugin;
use Moose;
use Future::AsyncAwait;
extends 'Langertha::Plugin';

has my_option => (is => 'ro', default => 42);

async sub plugin_before_llm_call {
    my ($self, $conversation, $iteration) = @_;
    # ... modify conversation ...
    return $conversation;
}

__PACKAGE__->meta->make_immutable;

# Or with sugar:
package Langertha::Plugin::MyPlugin;
use Langertha qw( Plugin );

has my_option => (is => 'ro', default => 42);

async sub plugin_before_llm_call { ... }

__PACKAGE__->meta->make_immutable;

DESCRIPTION

Base class for Langertha plugins. Plugins are Moose classes that extend Langertha::Plugin and override hook methods. Plugins can be attached to any plugin host — Langertha::Raider or an engine class that consumes Langertha::Role::PluginHost.

Plugins are registered via the plugins attribute on the host:

my $raider = Langertha::Raider->new(
    engine  => $engine,
    plugins => ['Langfuse', 'MyPlugin'],
);

Short names are resolved first to Langertha::Plugin::$name, then to LangerthaX::Plugin::$name. Fully qualified names (containing ::) are used as-is.

HOOK METHODS

Override these in your subclass. All hooks are async sub and form a pipeline: the host calls each plugin's hook in order, passing the return value of one as input to the next.

plugin_before_raid($messages) -> $messages

Transform input messages before the raid starts.

plugin_build_conversation($conversation) -> $conversation

Transform the assembled conversation (mission + history + messages).

plugin_before_llm_call($conversation, $iteration) -> $conversation

Transform the conversation before each LLM request.

plugin_after_llm_response($data, $iteration) -> $data

Inspect or transform the parsed LLM response.

plugin_before_tool_call($name, $input) -> ($name, $input) or ()

Inspect or transform before each tool execution. Return an empty list to skip the tool call.

plugin_after_tool_call($name, $input, $result) -> $result

Transform the tool result after execution.

plugin_after_raid($result) -> $result

Transform the final Langertha::Raider::Result before return.

host

Back-reference to the plugin host (Langertha::Raider or engine) this plugin belongs to. Weakened to avoid circular references.

raider

Convenience accessor. Returns the host if it is a Langertha::Raider, undef otherwise.

self_tools

sub self_tools {
    return [{
        name        => 'my_tool',
        description => 'Does something useful',
        inputSchema => { type => 'object', properties => { ... } },
        code        => sub { $_[0]->text_result('done') },
    }];
}

Override to register additional self-tools on the host. Returns an arrayref of tool definitions in MCP format. Tool codes receive ($mcp_tool, $args).

provides_events

sub provides_events { ['history_saved', 'history_compressed'] }

Override to declare custom events this plugin provides. Other plugins can hook into these events by implementing on_$event_name methods. The host validates at instantiation that all required events are provided.

requires_events

sub requires_events { ['history_saved'] }

Override to declare events this plugin depends on. If no loaded plugin provides a required event, the host dies with a useful error at instantiation.

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.