/ 
Langertha-0.503
/ Langertha::Engine::AKIAnthropic

NAME

Langertha::Engine::AKIAnthropic - AKI.IO via Anthropic-compatible API

VERSION

version 0.503

SYNOPSIS

use Langertha::Engine::AKIAnthropic;

my $aki = Langertha::Engine::AKIAnthropic->new(
    api_key => $ENV{LANGERTHA_AKI_API_KEY},
    model   => 'gemma4-26b',
);

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

DESCRIPTION

Provides access to AKI.IO via its Anthropic-compatible endpoint at https://aki.io/anthropic (the shared Langertha::Engine::AnthropicBase appends the /v1/messages path). AKI.IO is a European AI model hub based in Germany — all inference runs on EU infrastructure, fully GDPR-compliant.

This is the third face of the same provider: Langertha::Engine::AKI speaks the native API, Langertha::Engine::AKIOpenAI the OpenAI-compatible one, and this class the Anthropic Messages dialect. All three authenticate with the same AKI.IO key (LANGERTHA_AKI_API_KEY); pick whichever wire format your code already speaks.

The key is sent as a raw x-api-key header (no Bearer prefix). The anthropic-version header is accepted but not required by AKI.IO; the base class sends it anyway.

Model fallback for unknown IDs (substitute unconfirmed): AKI.IO's own documentation states it does not error on unknown model IDs — "Requests to unknown model names will fall back onto the Minimax M2.5 model." The exact substitute is version-dependent and Langertha could not re-confirm it live (2026-09-14 the /anthropic shim answered every request, documented models included, with HTTP 529), so treat the specific fallback model as unconfirmed. Either way, Claude model names and HuggingFace repository IDs are not a usable shortcut — an unknown ID is not the model you asked for. Always pass an exact AKI.IO model ID (list_models returns the documented set), and check $response->model (and watch for errors) if it matters which model replied.

Models documented for this endpoint: apertus-chat-70b, gpt-oss-120b, gemma4-26b, kimi-k2.7-code-1100b, llama3-chat-8b, llama3-chat-70b, minimax-m2.5-230b, mistral4-119b, qwen3.6-35b.

Tool calling works but is undocumented on this endpoint. AKI.IO's Anthropic compatibility page lists only model, messages, max_tokens, temperature, top_p, top_k, stop_sequences, stream and system as request parameters — no tools. It nevertheless accepts the native Anthropic tools array this class inherits from Langertha::Engine::AnthropicBase and answers with a tool_use block, verified live against llama3-chat-8b (2026-08-24, re-verified 2026-09-01; fixture t/data/akianthropic_tool_call_response.json). One deviation from real Anthropic: the input of that block arrives as a JSON string, not an object — Langertha::ToolCall decodes it, so $tc->arguments is a HashRef either way. Since the parameter is undocumented, AKI.IO owes it no stability; check $response->has_tool_calls rather than assuming.

Client errors arrive as HTTP 529: AKI.IO returns some caller-side errors as 529 overloaded_error — notably a token budget too small to finish a tool call ("Response finished before tool_call was completed! Try to raise max_gen_tokens"). That condition is deterministic and fixed by raising response_size / max_tokens, not transient server overload: do not treat an AKI 529 as a wait-and-retry signal, and read $error->{error}{message} for the real diagnostic.

Tool results carry text only. In the tool loop, an image a tool returns goes out as a text placeholder ([image] image/png (N bytes)) for every model: the shim accepts an image inside a tool_result but the model does not see it (live probe 2026-09-30). An embedded text resource goes out as a text block and a PDF as a placeholder, because the shim answers a document block there with 529 "Unsupported content type: document"; a native search_result block (also a 529) or document block becomes a text block with its text, with a warning.

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 — the same key the native and OpenAI-compatible AKI.IO engines use. If not provided, reads from the LANGERTHA_AKI_API_KEY environment variable. Sent as a raw x-api-key HTTP header (no Bearer prefix). Required.

default_model

Returns gpt-oss-120b, a current-generation non-MiniMax model AKI.IO rates "Supported", matching the default of the sibling Langertha::Engine::AKIOpenAI and replacing llama3-chat-8b, which AKI.IO marks end-of-life 2026-09-30. AKI.IO exposes MiniMax M3 only on its native endpoint, not this shim. AKI.IO documents no default of its own for this endpoint — an unset or unknown model resolves to a fallback AKI does not guarantee (its docs name Minimax M2.5; the live substitute is unconfirmed — see "DESCRIPTION"), so this class always sends an explicit model.

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.