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

/**
 * Outbound port for retrieving the list of available AI models from a provider endpoint.
 * <p>
 * This port is used exclusively by the GUI layer to populate the model selection control.
 * The headless batch path does not call this port; the model name is read directly from
 * the configuration file in that path.
 * <p>
 * <strong>Infrastructure neutrality:</strong> The port signature contains no HTTP client,
 * no JSON type, and no JavaFX reference. Implementations in {@code pdf-umbenenner-adapter-out}
 * translate the {@link ModelCatalogRequest} into provider-specific HTTP calls and map the
 * response back to a {@link ModelCatalogResult}.
 * <p>
 * <strong>Error handling contract:</strong> Implementations must never throw exceptions for
 * expected error conditions such as missing configuration values, authentication failures, or
 * unreachable endpoints. All such conditions are encoded as specific {@link ModelCatalogResult}
 * sub-types so the GUI can display them without crash handling.
 * <p>
 * <strong>Blocking behaviour:</strong> Implementations are expected to block the calling thread
 * until the result is available or the configured timeout expires. The GUI adapter must therefore
 * invoke this port on a background worker thread and must not call it on the JavaFX Application
 * Thread.
 */
public interface AiModelCatalogPort {

    /**
     * Fetches the list of available model identifiers for the provider described by the request.
     * <p>
     * The method always returns a non-{@code null} {@link ModelCatalogResult}. The caller
     * uses pattern matching over the sealed type hierarchy to distinguish success, empty list,
     * incomplete configuration, and technical failure without catching exceptions.
     *
     * @param request all information required to contact the provider endpoint;
     *                must not be {@code null}
     * @return the result of the catalogue retrieval; never {@code null}
     * @throws NullPointerException if {@code request} is {@code null}
     */
    ModelCatalogResult fetchAvailableModels(ModelCatalogRequest request);
}
