/ 
Langertha-Knarr-0.004
/ Langertha::Knarr::Config

NAME

Langertha::Knarr::Config - YAML configuration loader and validator

VERSION

version 0.004

SYNOPSIS

use Langertha::Knarr::Config;

# Load from file
my $config = Langertha::Knarr::Config->new(file => 'knarr.yaml');

# Build from environment (Docker zero-config mode)
my $config = Langertha::Knarr::Config->from_env;

# Validate
my @errors = $config->validate;
die join("\n", @errors) if @errors;

DESCRIPTION

Loads and validates Knarr configuration from a YAML file or from environment variables. All string values in the YAML file support ${ENV_VAR} interpolation.

See Langertha::Knarr for the full configuration file format reference.

file

Path to the YAML configuration file. Optional — when omitted the config object starts with an empty data hash (useful for testing or for configs built purely from environment variables via "from_env").

data

The raw configuration hashref, loaded from "file" and with all ${ENV_VAR} references expanded. Can be supplied directly to bypass file loading.

from_env

my $config = Langertha::Knarr::Config->from_env(%opts);

Class method. Builds a config object purely from environment variables (zero-config Docker mode). Calls "scan_env" to detect which API keys are set, assigns a sensible default model for each detected engine, enables auto_discover and passthrough, and sets OpenAI as the default engine when OPENAI_API_KEY is present.

Options are passed through to "scan_env" (e.g. include_test).

listen

ArrayRef of host:port strings to listen on. Defaults to ['127.0.0.1:8080', '127.0.0.1:11434'].

models

HashRef of model name → model definition hashref from the models: config section. Each definition may include engine, model, api_key_env, api_key, url, system_prompt, temperature, and response_size.

default_engine

HashRef from the default: config section, or undef if not set. At minimum contains engine. Used as the fallback when a model name is not explicitly configured and no passthrough URL matches.

langfuse

HashRef from the langfuse: config section. May contain url, public_key, secret_key, and trace_name. Returns an empty hashref when the section is absent.

proxy_api_key

Optional shared secret that clients must present in the Authorization: Bearer or x-api-key header. Falls back to the KNARR_API_KEY environment variable. When not set, the proxy is open (no auth required).

has_proxy_api_key

if ($config->has_proxy_api_key) { ... }

Returns true when a "proxy_api_key" is configured.

auto_discover

Boolean. When true, Langertha::Knarr::Router queries each configured engine for its model list at startup, making all discovered models available without explicit config entries. Defaults to 0.

passthrough

HashRef of format name → upstream base URL. passthrough: true in YAML enables all known formats with their default upstream URLs (https://api.openai.com and https://api.anthropic.com). Per-format URLs can be customised or set to false to disable selectively.

passthrough_url_for

my $url = $config->passthrough_url_for('openai');

Returns the upstream base URL for the given format name (e.g. openai or anthropic), or undef if passthrough is not configured for that format.

validate

my @errors = $config->validate;

Validates the configuration and returns a list of error strings. Returns an empty list when the config is valid. Checks that every model entry has an engine key, that the default engine (if set) has an engine key, and that at least one model or default engine is configured.

scan_env

my $found = Langertha::Knarr::Config->scan_env(
  env_files    => ['.env', '.env.local'],
  include_test => 1,
);

Class method. Scans %ENV and optional .env files for known API key environment variables. Returns a HashRef of engine name → {engine, api_key_env} for every engine whose key was found.

Priority order per engine: LANGERTHA_*_API_KEY beats the bare vendor key (e.g. OPENAI_API_KEY), which beats the TEST_LANGERTHA_*_API_KEY variant.

Options:

  • env_files — ArrayRef of .env file paths to parse (optional)

  • include_test — Include TEST_* variables (default: 1)

generate_config

my $yaml = Langertha::Knarr::Config->generate_config(
  engines => $found,       # from scan_env
  listen  => ['127.0.0.1:8080', '127.0.0.1:11434'],
);

Class method. Generates a YAML configuration string from scan_env results. The generated YAML includes sensible defaults for each detected engine and commented-out stanzas for optional features. Used by knarr init.

Returns a string.

SEE ALSO

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/langertha-knarr/issues.

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.