/ 
Langertha-0.503
/ Langertha::Engine::AKI

NAME

Langertha::Engine::AKI - AKI.IO native API

VERSION

version 0.503

SYNOPSIS

use Langertha::Engine::AKI;

my $aki = Langertha::Engine::AKI->new(
    api_key => $ENV{AKI_API_KEY},
    model   => 'llama3_8b_chat',
);

print $aki->simple_chat('Hello from Perl!');

# Get OpenAI-compatible API access
my $aki_openai = $aki->openai;
print $aki_openai->simple_chat('Hello via OpenAI format!');

# Get Anthropic-compatible API access
my $aki_anthropic = $aki->anthropic;
print $aki_anthropic->simple_chat('Hello via Anthropic format!');

DESCRIPTION

Provides access to AKI.IO's native API for running LLM inference. AKI.IO is a European AI model hub based in Germany; all inference runs on EU infrastructure, fully GDPR-compliant with no data leaving the EU.

The native API sends the API key as a key field in the JSON request body (not as an HTTP header). Supports synchronous chat, temperature and sampling controls, dynamic endpoint listing, MCP tool calling via Langertha::Role::HermesTools, OpenAI-compatible access via "openai", and Anthropic-compatible access via "anthropic".

Streaming is not yet supported in the native API. For streaming, use the OpenAI-compatible endpoint via $aki->openai.

The native API has no tools, tool_choice or response_format field: tools ride the system prompt (Hermes format), which cannot force a tool, so a tool_choice other than auto or none is dropped with a warning. To force a tool or get structured output, use Langertha::Engine::AKIOpenAI ($aki->openai).

tool_wire_format is fixed to hermes: the constructor croaks on any other value, since the native body has no field to carry native tools. Use Langertha::Engine::AKIOpenAI for OpenAI-format tools.

Get your API key at https://aki.io/ and set LANGERTHA_AKI_API_KEY.

THIS API IS WORK IN PROGRESS

api_key

The AKI.IO API key. If not provided, reads from LANGERTHA_AKI_API_KEY environment variable. Sent as a key field in the JSON request body (not as an HTTP header). Required.

default_model

Returns minimax_m3, AKI.IO's current-generation MiniMax M3 (428B) on the native endpoint. This replaces llama3_8b_chat, which AKI.IO marks end-of-life 2026-09-30. MiniMax is a per-account gated endpoint: a key without the entitlement is answered with "Client not authorized for endpoint minimax_m3!" rather than a silent model substitution, so check $response->model if it matters which model replied.

top_k

top_k => 40

Top-K sampling parameter. Controls the number of highest-probability tokens to consider at each generation step.

top_p

top_p => 0.9

Top-P (nucleus) sampling parameter. Controls the cumulative probability threshold for token selection.

max_gen_tokens

max_gen_tokens => 1000

Maximum number of tokens to generate in the response.

list_models

my $endpoints = $aki->list_models;
my $endpoints = $aki->list_models(force_refresh => 1);

Fetches available endpoint names from the AKI.IO GET /api/endpoints API. Returns an ArrayRef of endpoint names. Results are cached for models_cache_ttl seconds (default: 3600).

endpoint_details

my $details = $aki->endpoint_details('llama3_8b_chat');
# Returns hashref with name, title, description, workers, parameter_description, etc.

Fetches detailed information about a specific endpoint from the AKI.IO GET /api/endpoints/{name} API. Returns worker info, model metadata, and parameter descriptions.

chat_request

my $request = $aki->chat_request($messages, %extra);

Generates a native AKI.IO chat request. Posts to /api/call/{model} with messages encoded as JSON in the chat_context field. Includes key, temperature, top_k, top_p, max_gen_tokens, and wait_for_result parameters as configured. A model in %extra (a per-request model from "chat_f" in Langertha::Role::Chat or "model" in Langertha::Chat) replaces {model} in the URL for this request and is not sent in the body. Returns an HTTP request object.

chat_response

my $response = $aki->chat_response($http_response);

Parses a native AKI.IO chat response. Dies with an API error message if success is false. Returns a Langertha::Response with content, id (from the wire job_id), model, usage (from prompt_length / num_generated_tokens / num_cached_tokens), cached_tokens (lifted off usage), timing (total_seconds / compute_seconds, both already in seconds), tool_calls (Hermes <tool_call> tags), and raw. The native token counts differ from the OpenAI-compatible shim for the same prompt — check $response->model for which model answered.

openai

my $oai = $aki->openai;
my $oai = $aki->openai(model => 'llama3-chat-8b');

Returns a Langertha::Engine::AKIOpenAI instance configured with the same API key, system prompt, and temperature. Supports streaming and MCP tool calling.

Note: The native AKI model name is not carried over automatically because the /v1 endpoint uses different model identifiers. If no model is passed, the AKIOpenAI default model is used and a warning is emitted. Pass model => '...' explicitly with a valid /v1 model name to suppress the warning.

anthropic

my $anth = $aki->anthropic;
my $anth = $aki->anthropic(model => 'gemma4-26b');

Returns a Langertha::Engine::AKIAnthropic instance configured with the same API key, system prompt, and temperature. URL defaults to https://aki.io/anthropic (set on Langertha::Engine::AKIAnthropic itself, so it is not carried over from the native engine's https://aki.io base).

Note: The native AKI model name is not carried over automatically because the /anthropic endpoint uses different model identifiers. If no model is passed, the AKIAnthropic default model is used and a warning is emitted. Pass model => '...' explicitly with a valid /anthropic model name to suppress the warning. AKI.IO also silently routes unknown model IDs to MiniMax M2.5 — check $response->model if it matters which model replied.

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.