/ 
Langertha-0.503
/ Langertha::Role::PluginHost

NAME

Langertha::Role::PluginHost - Role for objects that host plugins (Raider, Engine)

VERSION

version 0.503

DESCRIPTION

Shared role consumed by Langertha::Raider, Langertha::Chat, Langertha::Embedder, Langertha::ImageGen, and engine classes to provide a plugin system with lifecycle management and a custom event bus.

Plugins are instantiated lazily on first use. Each plugin receives the host as its host attribute. Short names are resolved to Langertha::Plugin::$name or LangerthaX::Plugin::$name. Prefixing a name with + bypasses resolution and loads the class directly.

plugins

plugins => ['Langfuse']
plugins => [Langfuse => { trace_name => 'my-trace', auto_flush => 1 }]
plugins => [$plugin_instance]

ArrayRef of plugin specifications. Each entry may be:

  • A short name string (resolved to Langertha::Plugin::$name)

  • A short name followed by a HashRef of constructor args

  • A fully qualified class name (with or without + prefix)

  • An already-instantiated Langertha::Plugin object

plugin_instances

for my $plugin (@{ $host->plugin_instances }) {
  await $plugin->plugin_before_llm_call($conversation, $iteration);
}

Read-only ArrayRef of the instantiated Langertha::Plugin objects, in the order given in "plugins". Built lazily on first access: short names are resolved, constructed with "plugin_args" plus any per-plugin args and host => $self, and requires_events is checked against the loaded plugins' provides_events (dies when a required event has no provider). A host that runs its own hook chain (for example Langertha::Raider) iterates this list and calls the hook on each plugin itself.

_plugin_instances remains an alias of this reader.

plugin_args

plugins     => ['MyPlugin'],
plugin_args => { verbose => 1 },

HashRef of constructor arguments passed to every plugin the host builds from a name. Per-plugin args (Name => { ... } in "plugins") win over these; host always wins. Already-instantiated plugin objects are not touched.

The older constructor key _plugin_args is still accepted and used when plugin_args is not given; the _plugin_args reader is an alias of this one.

fire_event_f

my @results = await $host->fire_event_f('history_saved', $data);

Fires a custom event to all loaded plugins that implement on_$event_name. Returns a list of all plugin return values. Plugins declare the events they provide via "provides_events" in Langertha::Plugin and the events they require via "requires_events" in Langertha::Plugin.

SEE ALSO

plugin_pipeline_tool_call_f

my @call = await $host->plugin_pipeline_tool_call_f($name, $input);
return skipped_result() unless @call;
my ( $tool_name, $tool_input ) = @call;

Runs plugin_before_tool_call through every plugin in "plugin_instances", in order, as a pipeline: each plugin receives the ($name, $input) the previous one returned. Returns a Future resolving to the final ($name, $input) pair, or to the empty list as soon as any plugin returns the empty list, meaning the tool call is skipped (later plugins are not asked). With no plugins it returns the arguments unchanged. A plugin's failure fails the returned Future.

_plugin_pipeline_tool_call remains an alias of this method.

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/langertha/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 <getty@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus https://raudssus.de/.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.