<?php

namespace AIPT\Api\Chatbot;

/**
 * Interface for AI prompt building.
 *
 * @package AIPT\Api\Chatbot
 * @since 2.5.0
 */
interface PromptBuilderInterface {

    /**
     * Build system prompt with store context.
     *
     * @param array $settings Chatbot settings.
     * @return string System prompt text.
     */
    public function buildSystemPrompt(array $settings): string;

    /**
     * Build user prompt with message and product context.
     *
     * @param string $message  Customer's message.
     * @param array  $products Product data for context.
     * @param array  $settings Chatbot settings.
     * @param array  $history  Conversation history for context.
     * @return string User prompt text.
     */
    public function buildUserPrompt(string $message, array $products, array $settings, array $history = []): string;

    /**
     * Format products for prompt context.
     *
     * @param array $products Raw product data.
     * @param int   $max      Maximum products to include.
     * @return string Formatted product context.
     */
    public function formatProductContext(array $products, int $max = 10): string;

    /**
     * Get category list for prompt.
     *
     * @param array $category_ids Category IDs from index.
     * @return string Comma-separated category names.
     */
    public function getCategoryList(array $category_ids): string;
}
