first commit

src/Config/CatalogIntentConfig.php

@@ -1,12 +1,62 @@
 <?php
 
+declare(strict_types=1);
+
 namespace App\Config;
 
-class CatalogIntentConfig
+/**
+ * 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 similarity score. Prevents noise.
+    /**
+     * Minimum semantic similarity required before a catalog entity is accepted.
+     */
     public const MIN_SCORE = 0.72;
 
-    // Difference between Top 1 and Top 2, so that no uncertain match is accepted.
+    /**
+     * 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()
+    {
+    }
 }