<?php

declare(strict_types=1);

namespace Plugin\tnt_mcp\src\Ai;

use Plugin\tnt_mcp\src\Http\HttpClient;

/**
 * One completion the shop wants (epic 4.4) — everything a provider needs, in provider-neutral terms.
 *
 * It exists so {@see AiChatClient::complete()} has ONE parameter rather than eight, and so phase 4.5
 * can add a budget or a request id without touching every call site. The values arrive from the
 * `AiPrompt` action as strings out of the workflow argument store; parsing them into these types is
 * the action's job, so this object is always already valid.
 *
 * `model` may be '' — that means "the shop's configured default", resolved against the stored
 * {@see AiConfiguration} at call time rather than baked into the workflow, so switching the default
 * model repoints every workflow that did not deliberately pin one.
 */
final class AiPromptRequest
{
    /**
     * Anthropic REQUIRES a max token count on every request, so there has to be a default that is
     * not "unlimited". Roughly a page and a half of German prose — enough for the summaries,
     * classifications and short JSON documents a workflow step actually asks for.
     */
    public const DEFAULT_MAX_TOKENS = 1024;

    /** Above this a single workflow step turns into a bill nobody looked at. Phase 4.5 adds real budgets. */
    public const MAX_MAX_TOKENS = 16384;

    /** Attempts beyond the first. Kept low: a workflow action must not sit on a cron for minutes. */
    public const MAX_RETRIES = 3;

    public function __construct(
        public readonly string $prompt,
        public readonly string $systemPrompt = '',
        public readonly string $model = '',
        /** null means "do not send one" — every provider has its own sensible default. */
        public readonly ?float $temperature = null,
        public readonly int $maxTokens = self::DEFAULT_MAX_TOKENS,
        public readonly bool $json = false,
        public readonly int $timeout = HttpClient::DEFAULT_TIMEOUT,
        public readonly int $retries = 1,
    ) {
    }
}
