portal/app/app/Services/Bot/LlmClient.php

<?php

declare(strict_types=1);

namespace App\Services\Bot;

/**
 * Модель под капотом бота. Реализации: {@see YandexGptClient} (Яндекс, данные не покидают РФ)
 * и {@see AitunnelChatClient} (зарубежные модели через российский шлюз AITunnel).
 *
 * Какая используется — настройка `services.bot.llm` (yandex | aitunnel).
 */
interface LlmClient
{
    /**
     * @param  list<array{role: string, text: string}>  $history  прошлые реплики чата
     * @return string|null текст ответа; null — модель недоступна (бот уйдёт в эскалацию)
     */
    public function complete(string $systemPrompt, string $userText, array $history = []): ?string;
}