<?php

declare(strict_types=1);

namespace ContextPaging;

/**
 * Interface for OpenAI token counting operations.
 */
interface OpenAICompletionsInterface
{
    /**
     * Count tokens in a string.
     *
     * @param string $text The text to tokenize.
     * @param string $encoding One of: cl100k_base (GPT-4/3.5), o200k_base (GPT-4o/o1).
     * @return int Token count.
     * @throws \RuntimeException on process failure.
     */
    public function count(string $text, string $encoding = 'cl100k_base'): int;

    /**
     * Count tokens for an array of messages (chat format).
     * Concatenates all content with separator tokens for a rough count.
     *
     * @param array $messages Array of ['role' => '...', 'content' => '...']
     * @param string $encoding Encoding name.
     * @param int $perMessage Overhead tokens per message (4 for cl100k models).
     * @param int $replyPrimer Tokens added after all messages (3 for cl100k models).
     * @return int
     */
    public function contextSize(
        array $messages,
        string $encoding = 'cl100k_base',
        int $perMessage = 4,
        int $replyPrimer = 3
    ): int;
}
