/ 
Langertha-Raider-0.503
/ Langertha::Raider::Provider::Activation

NAME

Langertha::Raider::Provider::Activation - Internal activation of a provider manifest's endpoint as the engine of one raider run

VERSION

version 0.503

SYNOPSIS

# Internal to Langertha-Raider -- no API promise.
my $activation = Langertha::Raider::Provider::Activation->new(
  fetch => Langertha::Raider::Provider::Fetch->new( allow_internal => 0 ),
);
my $got = $activation->activate_f('provider.example',
  model => 'example-model', has_api_key => 1)->get;
# { status => 'completed', engine_name => 'openai',
#   engine_class => 'Langertha::Engine::OpenAI',
#   url => 'https://provider.example/v1', model => 'example-model', ... }
# { status => 'usage' | 'refused' | 'failed', error => ... }

DESCRIPTION

Internal module. Its interface may change without notice.

raider --provider: turns what a provider manifest (ADR 0007) claims into the engine of one run. Nothing is stored and nothing is trusted beyond this run: the release is the target named on the command line, as with -o url=.

1. The manifest is fetched with Langertha::Raider::Provider::Fetch and validated with Langertha::Manifest.
2. The model. The requested model must be a model id of the manifest. Without one, the manifest must list exactly one model id.
3. The endpoint is the one the model is listed on. A model listed on several endpoints takes the one whose dialect raider has an adapter for; when that is more than one, raider does not choose.
4. The dialect maps to a Langertha engine class ("engine_for_dialect"). An unknown dialect, or one raider cannot use ("unsupported_dialect"), is an error -- never a guess.
5. The origin. The endpoint's base_url must be https and of the same origin as the manifest, so a credential never goes to an origin the command line did not name. Its host is resolved and checked again, under the same address policy as the fetch (--allow-internal releases both): every address it resolves to must pass, as for the manifest.
6. The connection. The engine connects to the first of those checked addresses (connect_address, Langertha ADR 0037), never to the name resolved once more, so an answer that changes after the check (DNS rebinding) cannot send the request and its credential elsewhere. An address literal stands for itself. TLS still verifies the certificate against the host name. Unlike the manifest fetch, the engine has no second address to fall back to; an address with a scope (fe80::1%eth0) cannot be pinned and is an error.
7. The credential is the caller's: an endpoint with an auth_ref needs one (has_api_key), of an auth type raider knows.

A model that does not declare tools_native is a warning, not an error.

fetch

The Langertha::Raider::Provider::Fetch the manifest comes through; its allow_internal also releases the endpoint's host. Required.

engine_for_dialect

my ( $name, $class ) = $activation->engine_for_dialect('openai-chat');
# ( 'openai', 'Langertha::Engine::OpenAI' )

The raider engine name and the Langertha engine class of a manifest dialect; the empty list for a dialect raider has no adapter for. Also callable on the class.

mapped_dialects

The dialects "engine_for_dialect" maps, sorted. Also callable on the class.

unsupported_dialect

my $why = $activation->unsupported_dialect('lmstudio');

Why raider cannot use a dialect Langertha knows, or undef. Also callable on the class.

unsupported_dialects

The dialects "unsupported_dialect" names, sorted. Also callable on the class.

activate_f

my $got = await $activation->activate_f($target,
  model => $model_or_undef, has_api_key => $bool);

Resolves to a hash. status is completed, usage (the command line names a target that is none, a model the manifest does not list, no model where it lists several, or no key where the endpoint needs one), refused (the fetch policy, an endpoint that is not https or not of the manifest's origin, or an endpoint address the policy refuses) or failed (the fetch, an invalid manifest, a dialect or auth type raider cannot use, a manifest without models). Apart from completed, error says why.

A completed activation carries provider_id, manifest_url, endpoint (its id), dialect, engine_name, engine_class, url (the endpoint's base_url), model, auth (the auth id, or undef), addresses (of the endpoint host, all checked), connect_address (the one of them the engine connects to) and warnings. It never carries a credential.

choose_model

my ( $model, $refusal ) = $activation->choose_model($manifest, $requested);

The Langertha::Manifest::Model entry the run uses (see "DESCRIPTION"), or undef and the usage or failed result that says why not.

SEE ALSO

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/langertha-raider/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 <torsten@raudssus.de> https://raudssus.de/

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus.

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