/ 
Langertha-0.503
/ Langertha::Engine::Remote

NAME

Langertha::Engine::Remote - Base class for all remote engines

VERSION

version 0.503

SYNOPSIS

package My::Engine;
use Moose;

extends 'Langertha::Engine::Remote';

has '+url' => ( default => 'https://api.example.com' );

sub default_model { 'my-model' }

DESCRIPTION

Root base class for all HTTP-based LLM engines in Langertha. Composes Langertha::Role::JSON, Langertha::Role::HTTP, and Langertha::Role::PluginHost, and makes the url attribute required.

All engines in the distribution extend this class, either directly (Langertha::Engine::Anthropic, Langertha::Engine::Gemini, Langertha::Engine::Ollama, Langertha::Engine::AKI) or via the OpenAI-compatible intermediate class Langertha::Engine::OpenAIBase.

api_key_env

my $env = $class->api_key_env;

Class method returning the name of the environment variable this engine reads its API key from (LANGERTHA_*_API_KEY), or undef if the engine reads none at all. Derived from the class name by default; engines that share a vendor key override it (e.g. Langertha::Engine::AKIOpenAI reads LANGERTHA_AKI_API_KEY).

The name alone does not say whether the key is mandatory - pair it with "api_key_required".

api_key_required

my $needs_key = $class->api_key_required;

Class method returning true if the engine is unusable without credentials. Together with "api_key_env" it covers the three states an engine can be in:

Derived from "api_key_env" by default, so only engines with an optional key override it.

rate_limit

my $rl = $engine->rate_limit;

Returns the Langertha::RateLimit from the most recent API response, or undef if that response carried no rate limit headers — a response without them clears the previous one, so the value always describes the latest response. Error responses count: a 429 (or any other non-2xx) is recorded before the request croaks or its future fails, on the synchronous and every asynchronous path, so a caller can read requests_remaining, the resets and "retry_after" in Langertha::RateLimit after catching the error. Engines whose wire has no rate-limit headers (Gemini, Ollama native, AKI native, LM Studio native) still get a rate limit when a response sends Retry-After or retry-after-ms: it carries only "retry_after" in Langertha::RateLimit and "raw" in Langertha::RateLimit.

has_rate_limit

if ($engine->has_rate_limit) { ... }

Returns true if the engine has rate limit data from the most recent response.

generation_kwargs_for

my @kwargs = $engine->generation_kwargs_for(%$controls);

Emits the wire-agnostic generation-parameter kwargs that every chat dialect shares - the reasoning_kwargs_for and prompt_cache_kwargs_for outputs, each gated by can() so engines without those roles stay quiet. %controls is the per-request controls hash from chat_f (karr #46), passed wholesale; keys it does not carry fall back to the engine attributes inside the underlying "reasoning_kwargs_for" in Langertha::Role::ReasoningEffort and "prompt_cache_kwargs_for" in Langertha::Role::PromptCache. Returned as a list suitable for spreading into a request body. Dialect-specific emission (temperature, response_format, seed, knobs_kwargs_for, inference_geo, ...) stays at the call site because each dialect positions those fields at a specific place in the body.

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.