<?php

namespace interfaces;

interface system_search_intent_parser_i
{
    /**
     * Parse a natural-language search query into structured search hints.
     *
     * @param string $query The raw user query.
     * @param array $allowedEntityTypes Entity types the caller is allowed to search.
     * @param array $taxonomy Public taxonomy/aliases to improve intent parsing.
     * @return array{
     *   success: bool,
     *   normalized_query: string,
     *   aliases: array<int, string>,
     *   entity_hints: array<int, string>,
     *   confidence: float,
     *   association_hint: bool,
     *   fallback_reason: string|null,
     *   source: string
     * }
     */
    public function parse(string $query, array $allowedEntityTypes, array $taxonomy = []): array;
}