/ 
Langertha-0.503
/ Langertha::CallResult

NAME

Langertha::CallResult - Result of an embedding, transcription or image call, with usage, rate limit and timing

VERSION

version 0.503

SYNOPSIS

my $result = $engine->simple_embedding_result('Hello world');
my $vector = $result->value;              # what simple_embedding returns
say $result->usage->input_tokens if $result->has_usage;
say $result->rate_limit->requests_remaining if $result->has_rate_limit;
say $result->model, ' in ', $result->total_seconds, 's';

my $images = ( await $engine->simple_image_result_f('A cat') )->value;
my $text   = $engine->simple_transcription_call('speech.mp3')->value;

DESCRIPTION

The answer of one non-chat call (embedding, transcription, image generation) together with what the HTTP response said about it. "value" is exactly what the bare method (simple_embedding, simple_transcription, simple_image) returns; the other attributes are the provider's usage block, the rate limit of this response, the model that answered and the measured time.

It is deliberately not a Langertha::Response: that class is chat-shaped (it stringifies to content, carries tool_calls, thinking, finish_reason), and a vector or a list of images has none of that. See ADR 0034 in the distribution's docs/adr/.

value

The call's result, the same value the bare method returns: an embedding vector (ArrayRef of floats) or an ArrayRef of vectors for a batch, the transcript text, or the ArrayRef of image objects.

usage

A Langertha::Usage read from the response body by "from_raw" in Langertha::Usage: OpenAI embeddings' usage (prompt_tokens, total_tokens), a GPT image model's usage, a token-billed transcription's usage, Ollama's prompt_eval_count. Not set when the body reports none (Gemini embeddings, Whisper servers), and not set for a duration-billed transcription (usage => { type => 'duration', seconds => N }): it has no tokens to count, and its seconds stay in "raw". Check "has_usage" first.

rate_limit

The Langertha::RateLimit parsed from this response's headers, the same object "rate_limit" in Langertha::Engine::Remote returns right after the call. Not set when the response carried no rate limit headers.

model

The model that answered: the model field of the response body when the provider sends one (OpenAI embeddings do), otherwise the model that was requested. Not set when neither is known (a self-hosted embedding server called without a model).

total_seconds

Wall-clock seconds from sending the request to receiving the full response, measured by the client like "total_seconds" in Langertha::Response.

raw

The decoded response body when the provider answered JSON; not set for a plain-text body (a transcription with response_format text, srt or vtt). Fields Langertha does not lift (segments, duration, revised_prompt, ...) stay reachable here.

from_http_response

my $result = Langertha::CallResult->from_http_response( $engine, $http_response,
    value => $value, model => $requested_model, total_seconds => $seconds );

Builds the result of a call whose $http_response the engine has already parsed into $value (so an HTTP error has croaked before this point). Reads "raw", "usage" and the answering "model" from the body, and takes "rate_limit" from the engine, which recorded it from this response while parsing. model is the requested model, used when the body names none.

with_value

my $replaced = $result->with_value($new_value);

Returns a new Langertha::CallResult with $new_value as "value" and every other attribute copied; $result itself is unchanged. Used by Langertha::Embedder and Langertha::ImageGen when a plugin after-hook replaces the value.

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.