/ 
Langertha-0.503
/ Langertha::Embedder

NAME

Langertha::Embedder - Embedding abstraction wrapping an engine with optional model override

VERSION

version 0.503

SYNOPSIS

use Langertha::Engine::OpenAI;
use Langertha::Embedder;

my $engine = Langertha::Engine::OpenAI->new(
    api_key => $ENV{OPENAI_API_KEY},
    model   => 'text-embedding-3-small',
);

my $embedder = Langertha::Embedder->new(
    engine  => $engine,
    plugins => ['Langfuse'],
);

my $vector = $embedder->simple_embedding('Hello world');

# Override model per-embedder
my $large = Langertha::Embedder->new(
    engine => $engine,
    model  => 'text-embedding-3-large',
);

DESCRIPTION

Langertha::Embedder wraps any engine that consumes Langertha::Role::Embedding and adds an optional model override plus plugin lifecycle hooks via Langertha::Role::PluginHost.

Use this class when you need multiple embedding configurations from the same engine instance, or when you want plugin observability (e.g. Langertha::Plugin::Langfuse) without modifying the engine.

engine

The LLM engine to delegate embedding requests to. Must consume Langertha::Role::Embedding.

model

Optional model name override. When set, overrides the engine's embedding_model for requests made through this Embedder.

simple_embedding

my $vector = $embedder->simple_embedding($text);

Returns the embedding vector for $text; an ArrayRef of strings is one batch request and returns an ArrayRef of vectors in input order (the plugin hooks see the whole batch). If model is set, uses it as an override; otherwise delegates directly to the engine's simple_embedding. Plugin hooks plugin_before_embedding and plugin_after_embedding are fired around the request.

simple_embedding_f

my $vector = await $embedder->simple_embedding_f($text);

Async variant of "simple_embedding": the same result and plugin hooks, with the hooks awaited and the request sent through the engine's async backend (see "simple_embedding_f" in Langertha::Role::Embedding).

simple_embedding_result

my $result = $embedder->simple_embedding_result($text);
my $vector = $result->value;
say $result->usage->input_tokens if $result->has_usage;

Like "simple_embedding", with the same model override and plugin hooks, but returns the Langertha::CallResult of "simple_embedding_result" in Langertha::Role::Embedding: value is the vector after the after-hooks, and usage, rate_limit, model and total_seconds are the call's. plugin_after_embedding gets that CallResult as an extra third argument (see Langertha::Plugin). When a hook returns a different vector, the result is a new CallResult with that value and the other attributes copied.

simple_embedding_result_f

my $result = await $embedder->simple_embedding_result_f($text);

Async variant of "simple_embedding_result": the same result and hooks, sent through the engine's async backend like "simple_embedding_f".

SEE ALSO

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.