<?php

declare(strict_types=1);

namespace Plugin\tnt_mcp\src\Ai;

/**
 * Anything that can turn a prompt into an answer (epic 4.4).
 *
 * It exists so the `AiPrompt` action depends on the CAPABILITY rather than on
 * {@see AiChatClient} itself. Two things want that seam: the tests, which must drive the action
 * without a provider, and phase 4.5, whose budget guard and cost log wrap a completer around a
 * completer rather than growing another parameter on the client.
 */
interface AiCompleter
{
    /**
     * Never throws. Every failure — unconfigured shop, refused URL, dead transport, provider error,
     * unusable answer — comes back as a failed {@see AiChatResult} with a sentence saying which,
     * because the caller is a workflow action whose contract is a bool.
     */
    public function complete(AiPromptRequest $request): AiChatResult;
}
