<?php

declare(strict_types=1);

namespace Drupal\ai\Plugin\AiPlatform;

use Drupal\Component\Plugin\PluginInspectionInterface;
use Symfony\AI\Platform\PlatformInterface;

/**
 * Interface for ai_platform plugins.
 */
interface AiPlatformInterface extends PlatformInterface, PluginInspectionInterface {

  /**
   * Returns the translated plugin label.
   *
   * @return string
   *   The plugin label.
   */
  public function label(): string;

  /**
   * Returns the available configuration for an operation type and model.
   *
   * Returns an associative array keyed by configuration parameter name. Each
   * value is an array with the following keys:
   * - 'label': (string) Human-readable label.
   * - 'description': (string) Description of the parameter.
   * - 'type': (string) Data type ('integer', 'float', 'string', 'string_long').
   * - 'default': (mixed) Default value for the parameter.
   * - 'required': (bool) Whether the parameter is required.
   * - 'constraints': (array) Optional constraints, e.g. 'min', 'max', 'step',
   *   or 'options' for select lists.
   *
   * @param string $operation_type
   *   The operation type (e.g. 'chat', 'embeddings').
   * @param string $model_id
   *   The model ID.
   *
   * @return array<string, array{
   *   label: string,
   *   description: string,
   *   type: 'integer'|'float'|'string'|'string_long',
   *   default: mixed,
   *   required: bool,
   *   constraints?: array{
   *     min?: int|float,
   *     max?: int|float,
   *     step?: int|float,
   *     options?: array<string|int, string>,
   *   },
   *   }>
   *   The available configuration schema, keyed by parameter name.
   */
  public function getAvailableConfiguration(string $operation_type, string $model_id): array;

}
