<?php

declare(strict_types=1);

namespace App\Config;

/**
 * Central thresholds for deterministic catalog-entity detection.
 *
 * The values in this class intentionally define a conservative gate:
 * - only strong semantic tag hits may open the catalog path
 * - small score gaps between the best and second-best hit are treated as ambiguous
 */
final class CatalogIntentConfig
{
    /**
     * Minimum semantic similarity required before a catalog entity is accepted.
     */
    public const MIN_SCORE = 0.72;

    /**
     * Required distance between the best and second-best catalog entity hit.
     */
    public const AMBIGUITY_DELTA = 0.02;

    /**
     * Number of candidate tag hits to inspect during catalog intent detection.
     *
     * This is intentionally wider than the final accepted set so that strong
     * catalog_entity tags are not hidden behind generic tags in the raw result.
     */
    public const SEARCH_LIMIT = 6;

    /**
     * Conservative lower boundary for score normalization helpers.
     */
    public const MIN_ALLOWED_SCORE = 0.0;

    /**
     * Conservative upper boundary for score normalization helpers.
     */
    public const MAX_ALLOWED_SCORE = 1.0;

    public static function isScoreAccepted(float $score): bool
    {
        return $score >= self::MIN_SCORE;
    }

    public static function isAmbiguous(float $bestScore, float $secondScore): bool
    {
        return abs($bestScore - $secondScore) < self::AMBIGUITY_DELTA;
    }

    public static function clampScore(float $score): float
    {
        return max(self::MIN_ALLOWED_SCORE, min(self::MAX_ALLOWED_SCORE, $score));
    }

    private function __construct()
    {
    }
}