/ 
Langertha-0.503
/ Langertha::Role::Embedding

NAME

Langertha::Role::Embedding - Role for APIs with embedding functionality

VERSION

version 0.503

embedding_model

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

An engine whose default_embedding_model returns undef (the self-hosted vLLM, LlamaCpp and LM Studio servers) has no fixed embedding model: it uses the model you set, and without one sends no model field, so the server embeds with the model it serves.

embedding_dimensions

Optional size of the returned vectors, for models that can shorten them (OpenAI text-embedding-3-*, gemini-embedding-001, Mistral codestral-embed, matryoshka models on vLLM / SGLang). How it reaches the wire:

A matching extra passed to embedding_request wins over it, and an explicit dimensions extra is always sent untouched. Unset (the default), nothing is sent and the model answers in its native size.

embedding

my $request = $engine->embedding($text);

Builds and returns an embedding HTTP request object for the given $text. Use "simple_embedding" to execute the request and get the result directly.

simple_embedding

my $vector  = $engine->simple_embedding($text);
my $vectors = $engine->simple_embedding([ $text_a, $text_b ]);

Sends an embedding request for $text and returns the embedding vector (an ArrayRef of floats). An ArrayRef of strings is sent as one batch request and returns an ArrayRef of vectors, one per input and in input order. Blocks until the request completes. "simple_embedding_f" is the non-blocking variant.

simple_embedding_f

my $vector  = await $engine->simple_embedding_f($text);
my $vectors = await $engine->simple_embedding_f([ $text_a, $text_b ]);

Async variant of "simple_embedding": returns a Future that resolves to the same value (a vector, or an ArrayRef of vectors for an ArrayRef input) and fails with the same error text. The request goes through the engine's async backend (Langertha::Role::AsyncHTTP), so "user_agent_timeout" in Langertha::Role::HTTP bounds it on Net::Async::HTTP too; without that module it runs synchronously over LWP.

simple_embedding_result

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

my $large = $engine->simple_embedding_result($text, model => 'text-embedding-3-large');

Like "simple_embedding", but returns a Langertha::CallResult: the same vector (or ArrayRef of vectors for a batch) as value, plus the provider's usage, this response's rate_limit, the answering model and the measured total_seconds. Croaks like "simple_embedding". Optional %extra goes to embedding_request (e.g. a model override, which is then also the requested model of the result); Langertha::Embedder uses it for its model override.

simple_embedding_result_f

my $result = await $engine->simple_embedding_result_f(\@texts);

Async variant of "simple_embedding_result", sent like "simple_embedding_f": resolves to the Langertha::CallResult and fails with the same error text.

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.