<?php

declare(strict_types=1);

namespace Drupal\flowdrop\DTO\Tool;

/**
 * The set of tools available to a tool-consuming processor.
 *
 * Injected via {@see \Drupal\flowdrop\Plugin\FlowDropNodeProcessor\ToolsAwareInterface::setTools()}.
 * Lookups are by the model-facing name, so an unknown name (e.g. a hallucinated
 * tool call) resolves to NULL — a recoverable condition the consumer surfaces
 * back to its model.
 *
 * @extends \IteratorAggregate<int, \Drupal\flowdrop\DTO\Tool\ToolBindingInterface>
 *
 * @api
 */
interface ToolCollectionInterface extends \IteratorAggregate, \Countable {

  /**
   * All tool bindings in the set.
   *
   * @return array<int, \Drupal\flowdrop\DTO\Tool\ToolBindingInterface>
   *   The bindings.
   */
  public function all(): array;

  /**
   * Resolves a binding by its model-facing name.
   *
   * @param string $name
   *   The tool name.
   *
   * @return \Drupal\flowdrop\DTO\Tool\ToolBindingInterface|null
   *   The binding, or NULL if no tool has that name.
   */
  public function get(string $name): ?ToolBindingInterface;

  /**
   * Whether a tool with the given name exists.
   *
   * @param string $name
   *   The tool name.
   *
   * @return bool
   *   TRUE if present.
   */
  public function has(string $name): bool;

  /**
   * The neutral tool definitions for every tool in the set.
   *
   * @return array<int, array{name: string, description: string, input_schema: array<string, mixed>}>
   *   One definition per tool, ready to adapt into a provider tool manifest.
   */
  public function getDefinitions(): array;

}
