<?php
/**
 * Разбивка большого набора строк на запросы к провайдеру перевода.
 *
 * @package LingoCanvas
 */

declare(strict_types=1);

namespace LingoCanvas\Translation;

defined( 'ABSPATH' ) || exit;

/**
 * Пакует строки в группы по символьному бюджету — без участия пользователя
 * (ТЗ визуального редактора: «если текст не помещается в один запрос —
 * разбивай его автоматически»).
 *
 * Один элемент никогда не режется между чанками: разрыв абзаца пополам убил
 * бы контекст, ради которого весь материал вообще отправляется одним
 * заданием, а не по строке. Если единственный элемент сам больше бюджета
 * (огромная цитата), он едет один в своём чанке — это предел того, что можно
 * сделать, не разрезая строку.
 */
final class BatchChunker {

	/**
	 * Бюджет символов на один запрос по умолчанию.
	 *
	 * Было 6000 — с запасом под системный промпт и служебные JSON-обёртки,
	 * комфортно укладывающееся в контекст обычных моделей чата. Но не по
	 * времени: живой сбой (`cURL error 28`, 45 секунд, 0 байт) показал, что
	 * такой чанк иногда не успевает получить ответ от OpenAI в отведённый
	 * OpenAiProvider::TIMEOUT_SECONDS. Единичный абзац — маленький сегмент
	 * сам по себе — переводится тем же кодом стабильно; ломались именно
	 * укрупнённые чанки массового перевода.
	 *
	 * Меньший бюджет не гарантия против таймаута (ответ модели зависит и от
	 * её загруженности, не только от длины запроса), но кратно снижает
	 * шанс на него: короче запрос — короче и генерируемый ответ.
	 */
	public const DEFAULT_MAX_CHARS = 3000;

	/**
	 * Делит строки на чанки, сохраняя порядок.
	 *
	 * @param array<string, string> $items    Ключ => текст.
	 * @param int                   $maxChars Бюджет символов на чанк.
	 * @return list<array<string, string>>
	 */
	public static function chunk( array $items, int $maxChars = self::DEFAULT_MAX_CHARS ): array {
		$maxChars = max( 1, $maxChars );
		$chunks   = array();
		$current  = array();
		$size     = 0;

		foreach ( $items as $key => $text ) {
			$length = mb_strlen( $text );

			if ( array() !== $current && $size + $length > $maxChars ) {
				$chunks[] = $current;
				$current  = array();
				$size     = 0;
			}

			$current[ $key ] = $text;
			$size            += $length;
		}

		if ( array() !== $current ) {
			$chunks[] = $current;
		}

		return $chunks;
	}
}