docs(examples): enhance postgres-hybrid example with new features

- Demonstrate BM25TextSearchStrategy vs native PostgreSQL FTS
- Show explicit ReciprocalRankFusion configuration
- Add comparison between both text search strategies
- Simplify summary and improve clarity

Author: ahmed-bhs

examples/rag/postgres-hybrid.php

@@ -14,6 +14,9 @@
 use Symfony\AI\Fixtures\Movies;
 use Symfony\AI\Platform\Bridge\OpenAi\PlatformFactory;
 use Symfony\AI\Store\Bridge\Postgres\HybridStore;
+use Symfony\AI\Store\Bridge\Postgres\ReciprocalRankFusion;
+use Symfony\AI\Store\Bridge\Postgres\TextSearch\Bm25TextSearchStrategy;
+use Symfony\AI\Store\Bridge\Postgres\TextSearch\PostgresTextSearchStrategy;
 use Symfony\AI\Store\Document\Loader\InMemoryLoader;
 use Symfony\AI\Store\Document\Metadata;
 use Symfony\AI\Store\Document\TextDocument;
@@ -25,21 +28,26 @@
 require_once dirname(__DIR__).'/bootstrap.php';
 
 echo "=== PostgreSQL Hybrid Search Demo ===\n\n";
-echo "This example demonstrates how to configure the semantic ratio to balance\n";
-echo "between semantic (vector) search and PostgreSQL Full-Text Search.\n\n";
+echo "Demonstrates HybridStore with configurable search strategies:\n";
+echo "- Native PostgreSQL FTS vs BM25\n";
+echo "- Semantic ratio adjustment\n";
+echo "- Custom RRF scoring\n\n";
 
-// Initialize the hybrid store with balanced search (50/50)
 $connection = DriverManager::getConnection((new DsnParser())->parse(env('POSTGRES_URI')));
 $pdo = $connection->getNativeConnection();
 
 if (!$pdo instanceof PDO) {
     throw new RuntimeException('Unable to get native PDO connection from Doctrine DBAL.');
 }
 
+echo "=== Using BM25 Text Search Strategy ===\n\n";
+
 $store = new HybridStore(
     connection: $pdo,
     tableName: 'hybrid_movies',
-    semanticRatio: 0.5, // Balanced hybrid search by default
+    textSearchStrategy: new Bm25TextSearchStrategy('en'),
+    rrf: new ReciprocalRankFusion(k: 60, normalizeScores: true),
+    semanticRatio: 0.5,
 );
 
 // Create embeddings and documents
@@ -119,9 +127,42 @@
 // Cleanup
 $store->drop();
 
-echo "=== Summary ===\n";
-echo "- semanticRatio = 0.0: Best for exact keyword matches (PostgreSQL FTS)\n";
-echo "- semanticRatio = 0.5: Balanced approach using RRF (Reciprocal Rank Fusion)\n";
-echo "- semanticRatio = 1.0: Best for conceptual similarity searches (pgvector)\n";
-echo "\nYou can set the default ratio when instantiating the HybridStore,\n";
-echo "and override it per query using the 'semanticRatio' option.\n";
+echo "=== Comparing with Native PostgreSQL FTS ===\n\n";
+
+$storeFts = new HybridStore(
+    connection: $pdo,
+    tableName: 'hybrid_movies_fts',
+    textSearchStrategy: new PostgresTextSearchStrategy(),
+    semanticRatio: 0.5,
+);
+
+$storeFts->setup();
+$indexer = new Indexer(new InMemoryLoader($documents), $vectorizer, $storeFts, logger: logger());
+$indexer->index($documents);
+
+$resultsFts = $storeFts->query($queryEmbedding, [
+    'semanticRatio' => 0.5,
+    'q' => 'technology',
+    'limit' => 3,
+]);
+
+echo "Top 3 results (Native FTS):\n";
+foreach ($resultsFts as $i => $result) {
+    $metadata = $result->metadata->getArrayCopy();
+    echo sprintf(
+        "  %d. %s (Score: %.4f)\n",
+        $i + 1,
+        $metadata['title'] ?? 'Unknown',
+        $result->score ?? 0.0
+    );
+}
+
+$storeFts->drop();
+
+echo "\n=== Summary ===\n";
+echo "- semanticRatio = 0.0: Pure keyword matching\n";
+echo "- semanticRatio = 0.5: Balanced hybrid (RRF)\n";
+echo "- semanticRatio = 1.0: Pure semantic search\n";
+echo "\nText Search Strategies:\n";
+echo "- PostgresTextSearchStrategy: Native FTS (ts_rank_cd)\n";
+echo "- Bm25TextSearchStrategy: BM25 ranking (requires pg_bm25 extension)\n";

src/store/src/Bridge/Postgres/HybridStore.php

@@ -41,20 +41,20 @@ final class HybridStore implements ManagedStoreInterface, StoreInterface
     private readonly TextSearchStrategyInterface $textSearchStrategy;
 
     /**
-     * @param string                           $vectorFieldName         Name of the vector field
-     * @param string                           $contentFieldName        Name of the text field for FTS
-     * @param float                            $semanticRatio           Ratio between semantic and keyword search (0.0 to 1.0)
-     * @param Distance                         $distance                Distance metric for vector similarity
-     * @param string                           $language                PostgreSQL text search configuration
-     * @param TextSearchStrategyInterface|null $textSearchStrategy      Text search strategy (defaults to native PostgreSQL)
-     * @param ReciprocalRankFusion|null        $rrf                     RRF calculator (defaults to k=60, normalized)
-     * @param float|null                       $defaultMaxScore         Default max distance for vector search
-     * @param float|null                       $defaultMinScore         Default min RRF score threshold
-     * @param float                            $fuzzyPrimaryThreshold   Primary threshold for fuzzy matching
-     * @param float                            $fuzzySecondaryThreshold Secondary threshold for fuzzy matching
-     * @param float                                                         $fuzzyStrictThreshold    Strict threshold for double validation
-     * @param float                                                         $fuzzyWeight             Weight of fuzzy matching (0.0 to 1.0)
-     * @param array<string, array{metadata_key: string, boost?: float}>    $searchableAttributes    Searchable attributes with boosting config
+     * @param string                                                    $vectorFieldName         Name of the vector field
+     * @param string                                                    $contentFieldName        Name of the text field for FTS
+     * @param float                                                     $semanticRatio           Ratio between semantic and keyword search (0.0 to 1.0)
+     * @param Distance                                                  $distance                Distance metric for vector similarity
+     * @param string                                                    $language                PostgreSQL text search configuration
+     * @param TextSearchStrategyInterface|null                          $textSearchStrategy      Text search strategy (defaults to native PostgreSQL)
+     * @param ReciprocalRankFusion|null                                 $rrf                     RRF calculator (defaults to k=60, normalized)
+     * @param float|null                                                $defaultMaxScore         Default max distance for vector search
+     * @param float|null                                                $defaultMinScore         Default min RRF score threshold
+     * @param float                                                     $fuzzyPrimaryThreshold   Primary threshold for fuzzy matching
+     * @param float                                                     $fuzzySecondaryThreshold Secondary threshold for fuzzy matching
+     * @param float                                                     $fuzzyStrictThreshold    Strict threshold for double validation
+     * @param float                                                     $fuzzyWeight             Weight of fuzzy matching (0.0 to 1.0)
+     * @param array<string, array{metadata_key: string, boost?: float}> $searchableAttributes    Searchable attributes with boosting config
      */
     public function __construct(
         private readonly \PDO $connection,
@@ -75,17 +75,11 @@ public function __construct(
         private readonly array $searchableAttributes = [],
     ) {
         if ($semanticRatio < 0.0 || $semanticRatio > 1.0) {
-            throw new InvalidArgumentException(\sprintf(
-                'The semantic ratio must be between 0.0 and 1.0, "%s" given.',
-                $semanticRatio
-            ));
+            throw new InvalidArgumentException(\sprintf('The semantic ratio must be between 0.0 and 1.0, "%s" given.', $semanticRatio));
         }
 
         if ($fuzzyWeight < 0.0 || $fuzzyWeight > 1.0) {
-            throw new InvalidArgumentException(\sprintf(
-                'The fuzzy weight must be between 0.0 and 1.0, "%s" given.',
-                $fuzzyWeight
-            ));
+            throw new InvalidArgumentException(\sprintf('The fuzzy weight must be between 0.0 and 1.0, "%s" given.', $fuzzyWeight));
         }
 
         $this->textSearchStrategy = $textSearchStrategy ?? new PostgresTextSearchStrategy();
@@ -314,11 +308,11 @@ private function createSearchTextTrigger(): void
 
         $this->connection->exec(
             \sprintf(
-                "DROP TRIGGER IF EXISTS trigger_update_search_text ON %s;
+                'DROP TRIGGER IF EXISTS trigger_update_search_text ON %s;
                 CREATE TRIGGER trigger_update_search_text
                 BEFORE INSERT OR UPDATE ON %s
                 FOR EACH ROW
-                EXECUTE FUNCTION update_search_text();",
+                EXECUTE FUNCTION update_search_text();',
                 $this->tableName,
                 $this->tableName,
             ),
@@ -353,10 +347,7 @@ private function createTsvectorIndexes(): void
     private function validateSemanticRatio(float $ratio): float
     {
         if ($ratio < 0.0 || $ratio > 1.0) {
-            throw new InvalidArgumentException(\sprintf(
-                'The semantic ratio must be between 0.0 and 1.0, "%s" given.',
-                $ratio
-            ));
+            throw new InvalidArgumentException(\sprintf('The semantic ratio must be between 0.0 and 1.0, "%s" given.', $ratio));
         }
 
         return $ratio;

src/store/src/Bridge/Postgres/ReciprocalRankFusion.php

@@ -36,8 +36,8 @@ public function __construct(
     /**
      * Calculate RRF score for a single result with multiple rankings.
      *
-     * @param array<string, array{rank: int, score: float, weight: float}> $rankings
-     *        Each entry contains: rank (1-based), score (normalized 0-1), weight (0-1)
+     * @param array<string, array{rank: int|null, score: float, weight: float}> $rankings
+     *                                                                                    Each entry contains: rank (1-based or null), score (normalized 0-1), weight (0-1)
      *
      * @return float The combined RRF score
      */
@@ -142,7 +142,7 @@ public function buildCombinedSqlExpression(array $sources): string
             );
         }
 
-        return '(' . implode(' + ', $expressions) . ')';
+        return '('.implode(' + ', $expressions).')';
     }
 
     public function getK(): int

src/store/src/Bridge/Postgres/TextSearch/Bm25TextSearchStrategy.php

@@ -132,7 +132,7 @@ public function isAvailable(\PDO $connection): bool
                 "SELECT 1 FROM pg_proc WHERE proname = 'bm25topk' LIMIT 1"
             );
 
-            return $stmt->fetchColumn() !== false;
+            return false !== $stmt->fetchColumn();
         } catch (\PDOException) {
             return false;
         }