PHPLIB-1736: Add $scoreFusion stage

generator/config/stage/scoreFusion.yaml

@@ -0,0 +1,77 @@
+# yaml-language-server: $schema=../schema.json
+name: $scoreFusion
+link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/scoreFusion/'
+type:
+    - stage
+encode: object
+description: |
+    Combines multiple pipelines using relative score fusion to create hybrid search results.
+arguments:
+    -
+        name: input
+        type:
+            - object
+        description: |
+            An object with the following required fields:
+            - input.pipelines: Map from name to input pipeline. Each pipeline must be operating on the same collection. Minimum of one pipeline.
+            - input.normalization: Normalizes the score to the range 0 to 1 before combining the results. Value can be none, sigmoid or minMaxScaler.
+    -
+        name: combination
+        optional: true
+        type:
+            - object
+        description: |
+            An object with the following optional fields:
+            - combination.weights: Map from pipeline name to numbers (non-negative). If unspecified, default weight is 1 for each pipeline.
+            - combination.method: Specifies method for combining scores. Value can be avg or expression. Default is avg.
+            - combination.expression: This is the custom expression that is used when combination.method is set to expression.
+    -
+        name: scoreDetails
+        type:
+            - bool
+        default: false
+        description: Set to true to include detailed scoring information.
+tests:
+    -
+        name: 'Example'
+        link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/scoreFusion/#examples'
+        pipeline:
+        -
+            $scoreFusion:
+                input:
+                    pipelines:
+                        searchOne:
+                            -
+                                $vectorSearch:
+                                    index: 'vector_index'
+                                    path: 'plot_embedding'
+                                    queryVector: [-0.0016261312, -0.028070757, -0.011342932]
+                                    numCandidates: 150
+                                    limit: 10
+                        searchTwo:
+                            -
+                                $search:
+                                    index: '<INDEX_NAME>'
+                                    text:
+                                        query: '<QUERY_TERM>'
+                                        path: '<FIELD_NAME>'
+                    normalization: 'sigmoid'
+                combination:
+                    method: 'expression'
+                    expression:
+                        $sum:
+                            -
+                                $multiply:
+                                    - '$$searchOne'
+                                    - 10
+                            - '$$searchTwo'
+                scoreDetails: true
+        -
+            $project:
+                _id: 1
+                title: 1
+                plot: 1
+                scoreDetails:
+                    $meta: 'scoreDetails'
+        -
+            $limit: 20

tests/Builder/Stage/ScoreFusionStageTest.php

@@ -0,0 +1,73 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MongoDB\Tests\Builder\Stage;
+
+use MongoDB\Builder\Pipeline;
+use MongoDB\Builder\Stage;
+use MongoDB\Tests\Builder\PipelineTestCase;
+
+/**
+ * Test $scoreFusion stage
+ */
+class ScoreFusionStageTest extends PipelineTestCase
+{
+    public function testExample(): void
+    {
+        $pipeline = new Pipeline(
+            Stage::scoreFusion(
+                input: [
+                    'pipelines' => [
+                        'searchOne' => [
+                            [
+                                '$vectorSearch' => [
+                                    'index' => 'vector_index',
+                                    'path' => 'plot_embedding',
+                                    'queryVector' => [-0.0016261312, -0.028070757, -0.011342932],
+                                    'numCandidates' => 150,
+                                    'limit' => 10,
+                                ],
+                            ],
+                        ],
+                        'searchTwo' => [
+                            [
+                                '$search' => [
+                                    'index' => '<INDEX_NAME>',
+                                    'text' => [
+                                        'query' => '<QUERY_TERM>',
+                                        'path' => '<FIELD_NAME>',
+                                    ],
+                                ],
+                            ],
+                        ],
+                    ],
+                    'normalization' => 'sigmoid',
+                ],
+                combination: [
+                    'method' => 'expression',
+                    'expression' => [
+                        '$sum' => [
+                            [
+                                '$multiply' => [
+                                    '$$searchOne',
+                                    10,
+                                ],
+                            ],
+                            '$$searchTwo',
+                        ],
+                    ],
+                ],
+                scoreDetails: true,
+            ),
+            Stage::project(
+                _id: 1,
+                title: 1,
+                plot: 1,
+                scoreDetails: ['$meta' => 'scoreDetails'],
+            ),
+            Stage::limit(20),
+        );
+        $this->assertSamePipeline(Pipelines::ScoreFusionExample, $pipeline);
+    }
+}