/**
 * Outbound adapter for AI service invocation over OpenAI-compatible HTTP.
 * <p>
 * <strong>Responsibility:</strong>
 * This package encapsulates all HTTP communication, authentication, and transport-level
 * configuration for invoking an AI service. It translates between the abstract
 * {@link de.gecheckt.pdf.umbenenner.application.port.out.AiInvocationPort} and the
 * concrete OpenAI Chat Completions API (or compatible endpoints).
 * <p>
 * <strong>Architectural boundary:</strong>
 * <ul>
 *   <li>Input: {@link de.gecheckt.pdf.umbenenner.domain.model.AiRequestRepresentation}
 *       containing prompt, document text, and metadata</li>
 *   <li>Output: {@link de.gecheckt.pdf.umbenenner.application.port.out.AiInvocationResult}
 *       encoding either a successful HTTP response or a classified technical failure</li>
 * </ul>
 * <p>
 * <strong>What is encapsulated here (NOT exposed to Application/Domain):</strong>
 * <ul>
 *   <li>HTTP client library details</li>
 *   <li>Authentication header construction</li>
 *   <li>JSON serialization/deserialization of request/response</li>
 *   <li>Endpoint URL composition</li>
 *   <li>Timeout and connection configuration</li>
 *   <li>Error classification for technical failures (timeout, network, etc.)</li>
 *   <li>OpenAI Chat Completions API structure</li>
 * </ul>
 * <p>
 * <strong>What is NOT handled here (delegated to Application layer):</strong>
 * <ul>
 *   <li>JSON parsing of the response body into domain objects</li>
 *   <li>Validation of title, date, or reasoning fields</li>
 *   <li>Retry logic or retry classification</li>
 *   <li>Persistence of responses or request/response history</li>
 * </ul>
 * <p>
 * <strong>Technical error classification:</strong>
 * The adapter recognizes these as technical failures (retryable):
 * <ul>
 *   <li>Connection timeout</li>
 *   <li>Read timeout</li>
 *   <li>Endpoint unreachable (connection refused, DNS failure, etc.)</li>
 *   <li>Interrupted IO during request/response</li>
 *   <li>Other transport-level exceptions</li>
 * </ul>
 * <p>
 * A successful HTTP 200 response with unparseable or semantically invalid JSON is
 * <strong>not</strong> a technical failure; it is invocation success with a
 * problematic response body, which the Application layer will detect and classify.
 * <p>
 * <strong>Configuration usage:</strong>
 * The adapter receives startup configuration containing:
 * <ul>
 *   <li>{@code apiBaseUrl} — the base URL of the AI endpoint (e.g., https://api.openai.com)</li>
 *   <li>{@code apiModel} — the model name to request (e.g., gpt-4, local-llm)</li>
 *   <li>{@code apiTimeoutSeconds} — connection and read timeout in seconds</li>
 *   <li>{@code apiKey} — the authentication token, already resolved from env var or properties</li>
 * </ul>
 * <p>
 * These are not merely documented; they are <strong>actively used</strong> in the HTTP request.
 */
package de.gecheckt.pdf.umbenenner.adapter.out.ai;
