<?php

declare(strict_types=1);

namespace Drupal\flowdrop_chat\Service;

/**
 * Builds system prompts for the FlowDrop chat LLM.
 */
interface SystemPromptBuilderInterface {

  /**
   * Build the system prompt with injected context.
   *
   * @param array|string|null $workflowState
   *   The current workflow state as a decoded array, a JSON string, or NULL
   *   when no workflow context is available.
   * @param array<int, array{role: string, content: string}> $chatHistory
   *   The chat history as an array of role/content pairs.
   *
   * @return string
   *   The fully interpolated system prompt.
   */
  public function build(array|string|null $workflowState, array $chatHistory): string;

  /**
   * Builds the system prompt using pre-supplied node types JSON.
   *
   * Identical to build() but accepts a pre-built node types JSON string instead
   * of fetching from the node type manager. Intended for workflow nodes that
   * fetch node types separately (e.g. GetNodeTypes executor).
   *
   * @param array|string|null $workflowState
   *   The current workflow state.
   * @param string $nodeTypesJson
   *   Pre-built slimmed node types JSON (from GetNodeTypes node output).
   * @param string $template
   *   Optional template override. Empty string falls back to built-in default.
   *
   * @return string
   *   The fully interpolated system prompt (without history section).
   */
  public function buildWithNodeTypesJson(array|string|null $workflowState, string $nodeTypesJson, string $template = ''): string;

  /**
   * Returns all available node types as a slimmed JSON string.
   *
   * Fetches all node type definitions and reduces them to only the fields
   * the LLM needs (id, name, type, category, inputs, outputs, configSchema),
   * stripping descriptions, defaults, icons, tags, and other noise.
   *
   * @param string[] $exclude
   *   Optional list of node type IDs to exclude from the output.
   *
   * @return string
   *   A JSON-encoded array of slimmed node type objects.
   */
  public function getSlimNodeTypesJson(array $exclude = []): string;

}
