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

namespace Hafenstudios\Core\Ai;

defined( 'ABSPATH' ) || exit;

/**
 * Ein einzelner LLM-Aufruf als Wertobjekt (HANS-KI-KONZEPT Abschnitt 3).
 *
 * Jeder Aufruf traegt ein Zweck-Label (fuer Protokoll und spaetere Telemetrie,
 * NIE personenbezogen), einen optionalen System-Kontext, den eigentlichen
 * Prompt sowie ein Token-Budget und ein Timeout. Die Leitplanke "Fehler = stiller
 * Rueckfall" liegt beim AiClient, nicht hier: dieses Objekt beschreibt nur den
 * Wunsch, nicht die Ausfuehrung.
 */
final class AiRequest {

	/**
	 * Kurzes Zweck-Label, z.B. "mail_draft" oder "settings_test". Dient dem
	 * lokalen Protokoll und der aggregierten Telemetrie; enthaelt nie Kontaktdaten.
	 *
	 * @var string
	 */
	public string $purpose;

	/**
	 * System-Kontext (Tonalitaet, Rolle). Leer erlaubt.
	 *
	 * @var string
	 */
	public string $system;

	/**
	 * Der eigentliche Prompt (Nutzertext/Aufgabe).
	 *
	 * @var string
	 */
	public string $prompt;

	/**
	 * Obergrenze der zu erzeugenden Tokens.
	 *
	 * @var int
	 */
	public int $max_tokens;

	/**
	 * Timeout des HTTP-Aufrufs in Sekunden.
	 *
	 * @var int
	 */
	public int $timeout;

	/**
	 * @param string $purpose    Zweck-Label.
	 * @param string $prompt     Prompt.
	 * @param string $system     System-Kontext (optional).
	 * @param int    $max_tokens Token-Budget (Default 1024).
	 * @param int    $timeout    Timeout in Sekunden (Default 30).
	 */
	public function __construct( string $purpose, string $prompt, string $system = '', int $max_tokens = 1024, int $timeout = 30 ) {
		$this->purpose    = $purpose;
		$this->prompt     = $prompt;
		$this->system     = $system;
		$this->max_tokens = $max_tokens > 0 ? $max_tokens : 1024;
		$this->timeout    = $timeout > 0 ? $timeout : 30;
	}
}
