feat(nl-search): add natural language search models support

src/Client.php

@@ -85,6 +85,11 @@ class Client
      */
     public Conversations $conversations;
 
+    /**
+     * @var NLSearchModels
+     */
+    public NLSearchModels $nlSearchModels;
+
     /**
      * @var ApiCall
      */
@@ -115,6 +120,7 @@ public function __construct(array $config)
         $this->analytics     = new Analytics($this->apiCall);
         $this->stemming     = new Stemming($this->apiCall);
         $this->conversations = new Conversations($this->apiCall);
+        $this->nlSearchModels = new NLSearchModels($this->apiCall);
     }
 
     /**
@@ -220,4 +226,12 @@ public function getConversations(): Conversations
     {
         return $this->conversations;
     }
+
+    /**
+     * @return NLSearchModels
+     */
+    public function getNLSearchModels(): NLSearchModels
+    {
+        return $this->nlSearchModels;
+    }
 }

src/NLSearchModel.php

@@ -0,0 +1,73 @@
+<?php
+
+namespace Typesense;
+
+use Http\Client\Exception as HttpClientException;
+use Typesense\Exceptions\TypesenseClientError;
+
+/**
+ * Class NLSearchModel
+ *
+ * @package \Typesense
+ */
+class NLSearchModel
+{
+    /**
+     * @var string
+     */
+    private string $id;
+
+    /**
+     * @var ApiCall
+     */
+    private ApiCall $apiCall;
+
+    /**
+     * NLSearchModel constructor.
+     *
+     * @param string  $id
+     * @param ApiCall $apiCall
+     */
+    public function __construct(string $id, ApiCall $apiCall)
+    {
+        $this->id = $id;
+        $this->apiCall = $apiCall;
+    }
+
+    /**
+     * @param array $params
+     *
+     * @return array
+     * @throws TypesenseClientError|HttpClientException
+     */
+    public function update(array $params): array
+    {
+        return $this->apiCall->put($this->endPointPath(), $params);
+    }
+
+    /**
+     * @return array
+     * @throws TypesenseClientError|HttpClientException
+     */
+    public function retrieve(): array
+    {
+        return $this->apiCall->get($this->endPointPath(), []);
+    }
+
+    /**
+     * @return array
+     * @throws TypesenseClientError|HttpClientException
+     */
+    public function delete(): array
+    {
+        return $this->apiCall->delete($this->endPointPath());
+    }
+
+    /**
+     * @return string
+     */
+    public function endPointPath(): string
+    {
+        return sprintf('%s/%s', NLSearchModels::RESOURCE_PATH, encodeURIComponent($this->id));
+    }
+} 

src/NLSearchModels.php

@@ -0,0 +1,109 @@
+<?php
+
+namespace Typesense;
+
+use Http\Client\Exception as HttpClientException;
+use Typesense\Exceptions\TypesenseClientError;
+
+/**
+ * Class NLSearchModels
+ *
+ * @package \Typesense
+ */
+class NLSearchModels implements \ArrayAccess
+{
+    public const RESOURCE_PATH = '/nl_search_models';
+
+    /**
+     * @var ApiCall
+     */
+    private ApiCall $apiCall;
+
+    /**
+     * @var array
+     */
+    private array $nlSearchModels = [];
+
+    /**
+     * NLSearchModels constructor.
+     *
+     * @param ApiCall $apiCall
+     */
+    public function __construct(ApiCall $apiCall)
+    {
+        $this->apiCall = $apiCall;
+    }
+
+    /**
+     * @param $id
+     *
+     * @return mixed
+     */
+    public function __get($id)
+    {
+        if (isset($this->{$id})) {
+            return $this->{$id};
+        }
+        if (!isset($this->nlSearchModels[$id])) {
+            $this->nlSearchModels[$id] = new NLSearchModel($id, $this->apiCall);
+        }
+
+        return $this->nlSearchModels[$id];
+    }
+
+    /**
+     * @param array $params
+     *
+     * @return array
+     * @throws TypesenseClientError|HttpClientException
+     */
+    public function create(array $params): array
+    {
+        return $this->apiCall->post(static::RESOURCE_PATH, $params);
+    }
+
+    /**
+     * @return array
+     * @throws TypesenseClientError|HttpClientException
+     */
+    public function retrieve(): array
+    {
+        return $this->apiCall->get(static::RESOURCE_PATH, []);
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function offsetExists($offset): bool
+    {
+        return isset($this->nlSearchModels[$offset]);
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function offsetGet($offset): NLSearchModel
+    {
+        if (!isset($this->nlSearchModels[$offset])) {
+            $this->nlSearchModels[$offset] = new NLSearchModel($offset, $this->apiCall);
+        }
+
+        return $this->nlSearchModels[$offset];
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function offsetSet($offset, $value): void
+    {
+        $this->nlSearchModels[$offset] = $value;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function offsetUnset($offset): void
+    {
+        unset($this->nlSearchModels[$offset]);
+    }
+} 

tests/Feature/NLSearchModelsTest.php

@@ -0,0 +1,129 @@
+<?php
+
+namespace Feature;
+
+use Tests\NLSearchModelsTestCase;
+
+class NLSearchModelsTest extends NLSearchModelsTestCase
+{
+    public const RESOURCE_PATH = '/nl_search_models';
+
+    public function testCanCreateAModel(): void
+    {
+        $data = [
+            "id" => "test-collection-model",
+            "model_name" => "openai/gpt-3.5-turbo",
+            "api_key" => $_ENV['OPENAI_API_KEY'] ?? getenv('OPENAI_API_KEY'),
+            "system_prompt" => "You are a helpful search assistant.",
+            "max_bytes" => 16384,
+            "temperature" => 0.7
+        ];
+
+        $response = $this->client()->nlSearchModels->create($data);
+        $this->assertArrayHasKey('id', $response);
+        $this->assertEquals('test-collection-model', $response['id']);
+        $this->assertEquals('openai/gpt-3.5-turbo', $response['model_name']);
+
+        $this->client()->nlSearchModels['test-collection-model']->delete();
+    }
+
+    public function testCanRetrieveAllModels(): void
+    {
+        $testData = [
+            "id" => "retrieve-test-model",
+            "model_name" => "openai/gpt-3.5-turbo",
+            "api_key" => $_ENV['OPENAI_API_KEY'] ?? getenv('OPENAI_API_KEY'),
+            "system_prompt" => "Test model for retrieval.",
+            "max_bytes" => 8192
+        ];
+
+        $this->client()->nlSearchModels->create($testData);
+
+        $response = $this->client()->nlSearchModels->retrieve();
+        $this->assertIsArray($response);
+
+        $foundModel = false;
+        foreach ($response as $model) {
+            if ($model['id'] === 'retrieve-test-model') {
+                $foundModel = true;
+                $this->assertEquals('openai/gpt-3.5-turbo', $model['model_name']);
+                break;
+            }
+        }
+        $this->assertTrue($foundModel, 'Created test model should be found in the list');
+
+        $this->client()->nlSearchModels['retrieve-test-model']->delete();
+    }
+
+    public function testCreateWithMissingRequiredFields(): void
+    {
+        $incompleteData = [
+            "model_name" => "openai/gpt-3.5-turbo"
+        ];
+
+        $this->expectException(\Typesense\Exceptions\RequestMalformed::class);
+        $this->client()->nlSearchModels->create($incompleteData);
+    }
+
+    public function testCreateWithInvalidModelName(): void
+    {
+        $invalidData = [
+            "id" => "invalid-model-test",
+            "model_name" => "invalid/model-name",
+            "api_key" => $_ENV['OPENAI_API_KEY'] ?? getenv('OPENAI_API_KEY'),
+            "system_prompt" => "This should fail.",
+            "max_bytes" => 16384
+        ];
+
+        $this->expectException(\Typesense\Exceptions\RequestMalformed::class);
+        $this->client()->nlSearchModels->create($invalidData);
+    }
+
+    public function testUpdate(): void
+    {
+        $data = [
+            "id" => "test-collection-model",
+            "model_name" => "openai/gpt-3.5-turbo",
+            "api_key" => $_ENV['OPENAI_API_KEY'] ?? getenv('OPENAI_API_KEY'),
+            "system_prompt" => "You are a helpful search assistant.",
+            "max_bytes" => 16384,
+            "temperature" => 0.7
+        ];
+
+        $response = $this->client()->nlSearchModels->create($data);
+        $this->assertArrayHasKey('id', $response);
+        $this->assertEquals('test-collection-model', $response['id']);
+        $this->assertEquals('openai/gpt-3.5-turbo', $response['model_name']);
+
+        $response = $this->client()->nlSearchModels['test-collection-model']->update([
+            "temperature" => 0.5
+        ]);
+        $this->assertArrayHasKey('id', $response);
+        $this->assertEquals('test-collection-model', $response['id']);
+        $this->assertEquals(0.5, $response['temperature']);
+
+        $this->client()->nlSearchModels['test-collection-model']->delete();
+    }
+
+    public function testDelete(): void
+    {
+        $data = [
+            "id" => "test-collection-model",
+            "model_name" => "openai/gpt-3.5-turbo",
+            "api_key" => $_ENV['OPENAI_API_KEY'] ?? getenv('OPENAI_API_KEY'),
+            "system_prompt" => "You are a helpful search assistant.",
+            "max_bytes" => 16384,
+            "temperature" => 0.7
+        ];
+
+        $response = $this->client()->nlSearchModels->create($data);
+        $this->assertArrayHasKey('id', $response);
+        $this->assertEquals('test-collection-model', $response['id']);
+        $this->assertEquals('openai/gpt-3.5-turbo', $response['model_name']);
+
+        $response = $this->client()->nlSearchModels['test-collection-model']->delete();
+        $this->assertArrayHasKey('id', $response);
+        $this->assertEquals('test-collection-model', $response['id']);
+
+    }
+} 

tests/NLSearchModelsTestCase.php

@@ -0,0 +1,28 @@
+<?php
+
+namespace Tests;
+
+use Tests\TestCase;
+use Typesense\NLSearchModels;
+
+abstract class NLSearchModelsTestCase extends TestCase
+{
+    private NLSearchModels $mockNLSearchModels;
+
+    protected function setUp(): void
+    {
+        $apiKey = $_ENV['OPENAI_API_KEY'] ?? getenv('OPENAI_API_KEY') ?? null;
+        if (empty($apiKey)) {
+            $this->markTestSkipped('OPENAI_API_KEY environment variable is not set. Skipping NL Search Models tests.');
+            return;
+        }
+
+        parent::setUp();
+        $this->mockNLSearchModels = new NLSearchModels(parent::mockApiCall());
+    }
+
+    protected function mockNLSearchModels(): NLSearchModels
+    {
+        return $this->mockNLSearchModels;
+    }
+} 

tests/TestCase.php

@@ -89,6 +89,10 @@ protected function setUpDocuments(string $schema): void
 
     protected function tearDownTypesense(): void
     {
+        if ($this->typesenseClient === null) {
+            return;
+        }
+
         $collections = $this->typesenseClient->collections->retrieve();
         foreach ($collections as $collection) {
             $this->typesenseClient->collections[$collection['name']]->delete();