Merge #677

677: feat: Adds hybrid search options contract for multisearch r=brunoocasali a=apozeus

# Pull Request

## Related issue
Fixes #676

## What does this PR do?
Adds hybrid search options contract for multisearch

## PR checklist
Please check if your PR fulfills the following requirements:
- [x] Does this PR fix an existing issue, or have you listed the changes applied in the PR description (and why they are needed)?
- [x] Have you read the contributing guidelines?
- [x] Have you made sure that the title is accurate and descriptive of the changes?

Thank you so much for contributing to Meilisearch!


Co-authored-by: marksun <[email protected]>
Co-authored-by: apozeus <[email protected]>

src/Contracts/HybridSearchOptions.php

@@ -0,0 +1,46 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Meilisearch\Contracts;
+
+class HybridSearchOptions
+{
+    private ?float $semanticRatio = null;
+
+    /**
+     * @var non-empty-string|null
+     */
+    private ?string $embedder = null;
+
+    public function setSemanticRatio(float $ratio): HybridSearchOptions
+    {
+        $this->semanticRatio = $ratio;
+
+        return $this;
+    }
+
+    /**
+     * @param non-empty-string $embedder
+     */
+    public function setEmbedder(string $embedder): HybridSearchOptions
+    {
+        $this->embedder = $embedder;
+
+        return $this;
+    }
+
+    /**
+     * @return array{
+     *     semanticRatio?: float,
+     *     embedder?: non-empty-string
+     * }
+     */
+    public function toArray(): array
+    {
+        return array_filter([
+            'semanticRatio' => $this->semanticRatio,
+            'embedder' => $this->embedder,
+        ], static function ($item) { return null !== $item; });
+    }
+}

src/Contracts/SearchQuery.php

@@ -27,6 +27,7 @@ class SearchQuery
     private ?int $hitsPerPage;
     private ?int $page;
     private ?array $vector;
+    private ?HybridSearchOptions $hybrid = null;
     private ?array $attributesToSearchOn = null;
     private ?bool $showRankingScore = null;
     private ?bool $showRankingScoreDetails = null;
@@ -237,6 +238,21 @@ public function setVector(array $vector): SearchQuery
         return $this;
     }
 
+    /**
+     * This is an EXPERIMENTAL feature, which may break without a major version.
+     *
+     * Set hybrid search options
+     * (new HybridSearchOptions())
+     *     ->setSemanticRatio(0.8)
+     *     ->setEmbedder('manual');
+     */
+    public function setHybrid(HybridSearchOptions $hybridOptions): SearchQuery
+    {
+        $this->hybrid = $hybridOptions;
+
+        return $this;
+    }
+
     /**
      * @param list<non-empty-string> $attributesToSearchOn
      */
@@ -270,6 +286,7 @@ public function toArray(): array
             'hitsPerPage' => $this->hitsPerPage ?? null,
             'page' => $this->page ?? null,
             'vector' => $this->vector ?? null,
+            'hybrid' => null !== $this->hybrid ? $this->hybrid->toArray() : null,
             'attributesToSearchOn' => $this->attributesToSearchOn,
             'showRankingScore' => $this->showRankingScore,
             'showRankingScoreDetails' => $this->showRankingScoreDetails,