PHPLIB-1736: Add $scoreFusion stage

[kraenhansen]

Merging this PR will:

• Add the $scoreFusion as per its documentation.

Context: Working on COMPASS-8939 adding auto-complete support for $scoreFusion to mongosh.

[GromNaN]

I'll bet 20 Bonusly points that the Copilot agent can generate the PHP aggregation on the first try.

Thank you for contributing the PHP library.

[GromNaN]

That was a positive comment.
In fact, this file is generated, but it is a frame in which we have to write the code with the PHP aggregation builder. This allows us to validate the functioning of the aggregation builder and check the DX.
The tests/Builder/Stage has many examples of this.

The translation logic is very systematic, which means that an AI agent can easily guess what to write based on the expected extended JSON.
This is a suggestion that you complete this piece of code, but we can also take care of it.

[kraenhansen]

Pushed a commit 🤞

[codecov-commenter]

Codecov Report

❌ Patch coverage is 66.66667% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 81.68%. Comparing base (004a3c0) to head (dc813d1).
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
src/Builder/Stage/FluentFactoryTrait.php	0.00%	3 Missing ⚠️

❗ There is a different number of reports uploaded between BASE (004a3c0) and HEAD (dc813d1). Click for more details.

HEAD has 9 uploads less than BASE

Flag	BASE (004a3c0)	HEAD (dc813d1)
8.0-server	1	0
8.0-replica_set	5	0
6.0-replica_set	1	0
6.0-sharded_cluster	1	0
8.0-sharded_cluster	1	0

Additional details and impacted files

@@             Coverage Diff              @@
##               v2.x    #1811      +/-   ##
============================================
- Coverage     87.72%   81.68%   -6.05%     
- Complexity     3195     3198       +3     
============================================
  Files           424      425       +1     
  Lines          6296     6305       +9     
============================================
- Hits           5523     5150     -373     
- Misses          773     1155     +382     

Flag	Coverage Δ
6.0-replica_set	?
6.0-server	81.68% <66.66%> (-0.03%)	⬇️
6.0-sharded_cluster	?
8.0-replica_set	?
8.0-server	?
8.0-sharded_cluster	?

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[GromNaN]

Suggested change

	$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),
	);
	$pipeline = new Pipeline(
	Stage::scoreFusion(
	input: [
	'pipelines' => [
	'searchOne' => new Pipeline(
	Stage::vectorSearch(
	index: 'vector_index',
	path: 'plot_embedding',
	queryVector: [-0.0016261312, -0.028070757, -0.011342932],
	numCandidates: 150,
	limit: 10,
	),
	),
	'searchTwo' => new Pipeline(
	Stage::search(
	Search::text(
	query: '<QUERY_TERM>',
	path: '<FIELD_NAME>',
	),
	index: '<INDEX_NAME>',
	),
	),
	],
	'normalization' => 'sigmoid',
	],
	combination: [
	'method' => 'expression',
	'expression' => Expression::sum(
	Expression::multiply(
	Expression::variable('searchOne'),
	10,
	),
	Expression::variable('searchTwo'),
	),
	],
	scoreDetails: true,
	),
	Stage::project(
	_id: 1,
	title: 1,
	plot: 1,
	scoreDetails: Expression::meta('scoreDetails'),
	),
	Stage::limit(20),
	);