PHPLIB-1734: Add query and model arguments for automated embedding to $vectorSearch stage

[GromNaN]

• Depends on Add query and model arguments for autoEmbed to $vectorSearch stage mql-specifications#55
• To be rebased after PHPLIB-1771: Add arrayIndexAs support for $filter and $reduce operators #1936
  Fix PHPLIB-1734

Add the optional query (string) and model (string) arguments to the $vectorSearch pipeline stage, introduced in MongoDB 8.2 for the Automated Embedding feature.

These arguments allow passing a natural language text query instead of a pre-computed queryVector; MongoDB automatically generates the vector embedding at query time using the embedding model configured in the index, or an optionally overridden compatible model via model.

• queryVector is now optional (either queryVector or query must be provided)
• New query optional string argument (minVersion: '8.2')
• New model optional string argument (minVersion: '8.2')

[Copilot]

Pull request overview

Extends the aggregation builder’s $vectorSearch stage to support MongoDB 8.2 “automated embedding” usage by accepting a natural-language query and optional model override, in addition to the existing queryVector flow.

Changes:

• Added query and model arguments to VectorSearchStage (and corresponding factory methods).
• Made queryVector optional to enable query-text-based vector search.
• Added new pipeline fixtures and tests covering the new automated embedding examples.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/Builder/Stage/VectorSearchStage.php	Adds query/model properties and makes queryVector optional for $vectorSearch.
src/Builder/Stage/FactoryTrait.php	Updates Stage::vectorSearch() signature to accept optional queryVector, plus query/model.
src/Builder/Stage/FluentFactoryTrait.php	Updates fluent ->vectorSearch() signature and forwarding call to include query/model.
tests/Builder/Stage/VectorSearchStageTest.php	Adds new test cases building pipelines for automated embedding and model override.
tests/Builder/Stage/Pipelines.php	Adds canonical extended JSON fixtures for the new automated embedding pipelines.

Comments suppressed due to low confidence (1)

src/Builder/Stage/VectorSearchStage.php:154

• The stage currently allows constructing/encoding a $vectorSearch stage without either queryVector or query, even though the docblocks (and MongoDB 8.2 automated embedding semantics) require one of them. This results in an invalid pipeline being sent to the server. Consider validating that at least one of $queryVector or $query is provided, and that $model is only accepted when $query is set (as documented).

        $this->index = $index;
        $this->limit = $limit;
        $this->path = $path;
        if (is_array($queryVector) && ! array_is_list($queryVector)) {
            throw new InvalidArgumentException('Expected $queryVector argument to be a list, got an associative array.');