<?php

declare(strict_types=1);

namespace Drupal\flowdrop_chat\Service;

/**
 * Interface for the FlowDrop chat orchestration service.
 */
interface ChatServiceInterface {

  /**
   * Process a chat message through the full chat flow.
   *
   * Loads/saves history, builds system prompt, calls LLM, and returns response.
   *
   * @param string $workflowId
   *   The workflow ID.
   * @param string $message
   *   The user message.
   * @param array|string|null $workflowState
   *   The current workflow state as a decoded array, a JSON string, or NULL
   *   when no workflow context is available.
   *
   * @return array{content: string, conversationId: string}
   *   The LLM response and conversation identifier.
   */
  public function chat(string $workflowId, string $message, array|string|null $workflowState): array;

  /**
   * Get the chat history for a workflow.
   *
   * @param string $workflowId
   *   The workflow ID.
   *
   * @return array<int, array{role: string, content: string}>
   *   The chat history.
   */
  public function getHistory(string $workflowId): array;

  /**
   * Clear the chat history for a workflow.
   *
   * @param string $workflowId
   *   The workflow ID.
   */
  public function clearHistory(string $workflowId): void;

}
