package de.gecheckt.pdf.umbenenner.application.port.out.modelcatalog;

/**
 * Describes the origin of the effective API key value for a provider.
 * <p>
 * The resolution order is defined in the application configuration rules:
 * <ol>
 *   <li>A provider-specific environment variable takes the highest precedence.</li>
 *   <li>For the {@code openai-compatible} provider family a legacy environment variable
 *       is evaluated as a secondary fallback for backward compatibility.</li>
 *   <li>The property value from the {@code .properties} file is used when no
 *       environment variable is present.</li>
 *   <li>{@link #ABSENT} is returned when none of the above sources supplies a value.</li>
 * </ol>
 * <p>
 * This enum is placed in the Application module because the resolution order is a fachliche
 * rule that applies independently of the GUI. Bootstrap uses the same precedence, and
 * future diagnostic components outside the GUI may need to report key provenance without
 * depending on GUI-layer types.
 */
public enum ApiKeyOrigin {

    /**
     * The effective key comes from the provider-specific environment variable
     * (e.g., {@code ANTHROPIC_API_KEY} for Claude or {@code OPENAI_API_KEY} for
     * OpenAI-compatible providers).
     */
    FROM_PROVIDER_ENV_VAR,

    /**
     * The effective key comes from the legacy environment variable accepted for
     * backward compatibility.
     * <p>
     * This origin applies only to the {@code openai-compatible} provider family. The
     * legacy variable name is defined by the adapter and is not fixed in this enum.
     */
    FROM_LEGACY_ENV_VAR,

    /**
     * The effective key comes from the property value stored in the {@code .properties} file.
     */
    FROM_PROPERTY_FILE,

    /**
     * No API key value was found in any of the supported sources.
     * <p>
     * The provider configuration is incomplete; the batch run cannot start and the GUI
     * must indicate that the key is missing.
     */
    ABSENT
}
