package de.gecheckt.pdf.umbenenner.application.config.provider;

/**
 * Immutable configuration for a single AI provider family.
 * <p>
 * Holds all parameters needed to connect to and authenticate with one AI provider endpoint.
 * Instances are created by the configuration parser in the adapter layer; validation
 * of required fields is performed by the corresponding validator.
 *
 * <h2>Field semantics</h2>
 * <ul>
 *   <li>{@code model} – the AI model name; required for the active provider, may be {@code null}
 *       for the inactive provider.</li>
 *   <li>{@code timeoutSeconds} – HTTP connection/read timeout in seconds; must be positive for
 *       the active provider. {@code 0} indicates the value was not configured.</li>
 *   <li>{@code baseUrl} – the base URL of the API endpoint. For the Anthropic Claude family a
 *       default of {@code https://api.anthropic.com} is applied by the parser when the property
 *       is absent; for the OpenAI-compatible family it is required and may not be {@code null}.</li>
 *   <li>{@code apiKey} – the resolved API key after environment-variable precedence has been
 *       applied; may be blank for the inactive provider, must not be blank for the active provider.</li>
 * </ul>
 *
 * @param model          the AI model name; {@code null} when not configured
 * @param timeoutSeconds HTTP timeout in seconds; {@code 0} when not configured
 * @param baseUrl        the base URL of the API endpoint; {@code null} when not configured
 *                       (only applicable to providers without a built-in default)
 * @param apiKey         the resolved API key; blank when not configured
 */
public record ProviderConfiguration(
        String model,
        int timeoutSeconds,
        String baseUrl,
        String apiKey) {
}
