<?php
/**
 * @package Hafenstudios\Core
 */

namespace Hafenstudios\Core\Ai;

defined( 'ABSPATH' ) || exit;

/**
 * Vertrag fuer LLM-Treiber (HANS-KI-KONZEPT Abschnitt 3, Muster MailDriver).
 *
 * Ein Treiber kapselt genau einen Anbieterzugang (BYO Anthropic, BYO
 * OpenAI-kompatibel, Hafenstudios-Proxy) hinter einer einheitlichen Methode.
 * Der Treiber wirft keine Ausnahme nach aussen; jeder Fehler ist ein AiResult
 * mit ok=false.
 */
interface AiDriver {

	/**
	 * Fuehrt einen LLM-Aufruf aus.
	 *
	 * @param AiRequest $request Der Aufruf.
	 * @return AiResult
	 */
	public function complete( AiRequest $request ): AiResult;

	/**
	 * Eindeutiger Treiber-Schluessel, z.B. "anthropic", "openai_compat", "proxy".
	 *
	 * @return string
	 */
	public function key(): string;
}
