feat: implement Gemini File Search APIs (Stores & Documents)

README.md

@@ -49,6 +49,17 @@
       - [Update Cached Content](#update-cached-content)
       - [Delete Cached Content](#delete-cached-content)
       - [Use Cached Content](#use-cached-content)
+    - [File Search Stores](#file-search-stores)
+      - [Create File Search Store](#create-file-search-store)
+      - [Get File Search Store](#get-file-search-store)
+      - [List File Search Stores](#list-file-search-stores)
+      - [Delete File Search Store](#delete-file-search-store)
+      - [Update File Search Store](#update-file-search-store)
+    - [File Search Documents](#file-search-documents)
+      - [Create File Search Document](#create-file-search-document)
+      - [Get File Search Document](#get-file-search-document)
+      - [List File Search Documents](#list-file-search-documents)
+      - [Delete File Search Document](#delete-file-search-document)
     - [Embedding Resource](#embedding-resource)
     - [Models](#models)
         - [List Models](#list-models)
@@ -834,6 +845,125 @@ echo "Cached tokens used: {$response->usageMetadata->cachedContentTokenCount}\n"
 echo "New tokens used: {$response->usageMetadata->promptTokenCount}\n";
 ```
 
+### File Search Stores
+
+File search allows you to search files that were uploaded through the File API.
+
+#### Create File Search Store
+Create a file search store.
+
+```php
+use Gemini\Enums\FileState;
+use Gemini\Enums\MimeType;
+use Gemini\Enums\Schema;
+use Gemini\Enums\DataType;
+
+$files = $client->files();
+echo "Uploading\n";
+$meta = $files->upload(
+    filename: 'document.pdf',
+    mimeType: MimeType::APPLICATION_PDF,
+    displayName: 'Document for search'
+);
+echo "Processing";
+do {
+    echo ".";
+    sleep(2);
+    $meta = $files->metadataGet($meta->uri);
+} while (! $meta->state->complete());
+echo "\n";
+
+if ($meta->state == FileState::Failed) {
+    die("Upload failed:\n".json_encode($meta->toArray(), JSON_PRETTY_PRINT));
+}
+
+$fileSearchStore = $client->fileSearchStores()->create(
+    displayName: 'My Search Store',
+);
+
+echo "File search store created: {$fileSearchStore->name}\n";
+```
+
+#### Get File Search Store
+Get a specific file search store by name.
+
+```php
+$fileSearchStore = $client->fileSearchStores()->get('fileSearchStores/my-search-store');
+
+echo "Name: {$fileSearchStore->name}\n";
+echo "Display Name: {$fileSearchStore->displayName}\n";
+```
+
+#### List File Search Stores
+List all file search stores.
+
+```php
+$response = $client->fileSearchStores()->list(pageSize: 10);
+
+foreach ($response->fileSearchStores as $fileSearchStore) {
+    echo "Name: {$fileSearchStore->name}\n";
+    echo "Display Name: {$fileSearchStore->displayName}\n";
+    echo "--- \n";
+}
+```
+
+#### Delete File Search Store
+Delete a file search store by name.
+
+```php
+$client->fileSearchStores()->delete('fileSearchStores/my-search-store');
+```
+
+### File Search Documents
+
+#### Upload File Search Document
+Upload a local file directly to a file search store.
+
+```php
+use Gemini\Enums\MimeType;
+
+$response = $client->fileSearchStores()->upload(
+    storeName: 'fileSearchStores/my-search-store',
+    filename: 'document2.pdf',
+    mimeType: MimeType::APPLICATION_PDF,
+    displayName: 'Another Search Document'
+);
+
+echo "File search document upload operation: {$response->name}\n";
+```
+
+#### Get File Search Document
+Get a specific file search document by name.
+
+```php
+$fileSearchDocument = $client->fileSearchStores()->getDocument('fileSearchStores/my-search-store/fileSearchDocuments/my-document');
+
+echo "Name: {$fileSearchDocument->name}\n";
+echo "Display Name: {$fileSearchDocument->displayName}\n";
+```
+
+#### List File Search Documents
+List all file search documents within a store.
+
+```php
+$response = $client->fileSearchStores()->listDocuments(storeName: 'fileSearchStores/my-search-store', pageSize: 10);
+
+foreach ($response->documents as $fileSearchDocument) {
+    echo "Name: {$fileSearchDocument->name}\n";
+    echo "Display Name: {$fileSearchDocument->displayName}\n";
+    echo "Create Time: {$fileSearchDocument->createTime}\n";
+    echo "Update Time: {$fileSearchDocument->updateTime}\n";
+    echo "--- \n";
+}
+```
+
+#### Delete File Search Document
+Delete a file search document by name.
+
+```php
+$client->fileSearchStores()->deleteDocument('fileSearchStores/my-search-store/fileSearchDocuments/my-document');
+```
+
 ### Embedding Resource
 Embedding is a technique used to represent information as a list of floating point numbers in an array. With Gemini, you can represent text (words, sentences, and blocks of text) in a vectorized form, making it easier to compare and contrast embeddings. For example, two texts that share a similar subject matter or sentiment should have similar embeddings, which can be identified through mathematical comparison techniques such as cosine similarity.
 

src/Client.php

@@ -8,13 +8,15 @@
 use Gemini\Contracts\ClientContract;
 use Gemini\Contracts\Resources\CachedContentsContract;
 use Gemini\Contracts\Resources\FilesContract;
+use Gemini\Contracts\Resources\FileSearchStoresContract;
 use Gemini\Contracts\Resources\GenerativeModelContract;
 use Gemini\Contracts\TransporterContract;
 use Gemini\Enums\ModelType;
 use Gemini\Resources\CachedContents;
 use Gemini\Resources\ChatSession;
 use Gemini\Resources\EmbeddingModel;
 use Gemini\Resources\Files;
+use Gemini\Resources\FileSearchStores;
 use Gemini\Resources\GenerativeModel;
 use Gemini\Resources\Models;
 
@@ -81,4 +83,9 @@ public function cachedContents(): CachedContentsContract
     {
         return new CachedContents($this->transporter);
     }
+
+    public function fileSearchStores(): FileSearchStoresContract
+    {
+        return new FileSearchStores($this->transporter);
+    }
 }

src/Contracts/ClientContract.php

@@ -9,6 +9,7 @@
 use Gemini\Contracts\Resources\ChatSessionContract;
 use Gemini\Contracts\Resources\EmbeddingModalContract;
 use Gemini\Contracts\Resources\FilesContract;
+use Gemini\Contracts\Resources\FileSearchStoresContract;
 use Gemini\Contracts\Resources\GenerativeModelContract;
 use Gemini\Contracts\Resources\ModelContract;
 
@@ -35,4 +36,6 @@ public function chat(BackedEnum|string $model): ChatSessionContract;
     public function files(): FilesContract;
 
     public function cachedContents(): CachedContentsContract;
+
+    public function fileSearchStores(): FileSearchStoresContract;
 }

src/Contracts/Resources/FileSearchStoresContract.php

@@ -0,0 +1,70 @@
+<?php
+declare(strict_types=1);
+
+namespace Gemini\Contracts\Resources;
+
+use Gemini\Enums\MimeType;
+use Gemini\Responses\FileSearchStores\Documents\DocumentResponse;
+use Gemini\Responses\FileSearchStores\Documents\ListResponse as DocumentListResponse;
+use Gemini\Responses\FileSearchStores\FileSearchStoreResponse;
+use Gemini\Responses\FileSearchStores\ListResponse;
+use Gemini\Responses\FileSearchStores\UploadResponse;
+
+interface FileSearchStoresContract
+{
+    /**
+     * Create a file search store.
+     *
+     * @see https://ai.google.dev/api/file-search/file-search-stores#method:-fileSearchStores.create
+     */
+    public function create(?string $displayName = null): FileSearchStoreResponse;
+
+    /**
+     * Get a file search store.
+     *
+     * @see https://ai.google.dev/api/file-search/file-search-stores#method:-fileSearchStores.get
+     */
+    public function get(string $name): FileSearchStoreResponse;
+
+    /**
+     * List file search stores.
+     *
+     * @see https://ai.google.dev/api/file-search/file-search-stores#method:-fileSearchStores.list
+     */
+    public function list(?int $pageSize = null, ?string $nextPageToken = null): ListResponse;
+
+    /**
+     * Delete a file search store.
+     *
+     * @see https://ai.google.dev/api/file-search/file-search-stores#method:-fileSearchStores.delete
+     */
+    public function delete(string $name, bool $force = false): void;
+
+    /**
+     * Upload a file to a file search store.
+     *
+     * @see https://ai.google.dev/api/file-search/file-search-stores#method:-media.uploadtofilesearchstore
+     */
+    public function upload(string $storeName, string $filename, ?MimeType $mimeType = null, ?string $displayName = null): UploadResponse;
+
+    /**
+     * List documents in a file search store.
+     *
+     * @see https://ai.google.dev/api/file-search/documents#method:-fileSearchStores.documents.list
+     */
+    public function listDocuments(string $storeName, ?int $pageSize = null, ?string $nextPageToken = null): DocumentListResponse;
+
+    /**
+     * Get a document.
+     *
+     * @see https://ai.google.dev/api/file-search/documents#method:-fileSearchStores.documents.get
+     */
+    public function getDocument(string $name): DocumentResponse;
+
+    /**
+     * Delete a document.
+     *
+     * @see https://ai.google.dev/api/file-search/documents#method:-fileSearchStores.documents.delete
+     */
+    public function deleteDocument(string $name, bool $force = false): void;
+}

src/Requests/FileSearchStores/CreateRequest.php

@@ -0,0 +1,42 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Gemini\Requests\FileSearchStores;
+
+use Gemini\Enums\Method;
+use Gemini\Foundation\Request;
+use Gemini\Requests\Concerns\HasJsonBody;
+
+/**
+ * @link https://ai.google.dev/api/file-search/file-search-stores#method:-fileSearchStores.create
+ */
+class CreateRequest extends Request
+{
+    use HasJsonBody;
+
+    protected Method $method = Method::POST;
+
+    public function __construct(
+        public ?string $displayName = null,
+    ) {}
+
+    public function resolveEndpoint(): string
+    {
+        return 'fileSearchStores';
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function defaultBody(): array
+    {
+        $body = [];
+
+        if ($this->displayName !== null) {
+            $body['displayName'] = $this->displayName;
+        }
+
+        return $body;
+    }
+}

src/Requests/FileSearchStores/DeleteRequest.php

@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Gemini\Requests\FileSearchStores;
+
+use Gemini\Enums\Method;
+use Gemini\Foundation\Request;
+
+/**
+ * @link https://ai.google.dev/api/file-search/file-search-stores#method:-fileSearchStores.delete
+ */
+class DeleteRequest extends Request
+{
+    protected Method $method = Method::DELETE;
+
+    public function __construct(
+        protected readonly string $name,
+        protected readonly bool $force = false,
+    ) {}
+
+    public function resolveEndpoint(): string
+    {
+        return $this->name;
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function defaultQuery(): array
+    {
+        return $this->force ? ['force' => 'true'] : [];
+    }
+}

src/Requests/FileSearchStores/Documents/DeleteRequest.php

@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Gemini\Requests\FileSearchStores\Documents;
+
+use Gemini\Enums\Method;
+use Gemini\Foundation\Request;
+
+/**
+ * @link https://ai.google.dev/api/file-search/documents#method:-fileSearchStores.documents.delete
+ */
+class DeleteRequest extends Request
+{
+    protected Method $method = Method::DELETE;
+
+    public function __construct(
+        protected readonly string $name,
+        protected readonly bool $force = false,
+    ) {}
+
+    public function resolveEndpoint(): string
+    {
+        return $this->name;
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function defaultQuery(): array
+    {
+        return $this->force ? ['force' => 'true'] : [];
+    }
+}

src/Requests/FileSearchStores/Documents/GetRequest.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Gemini\Requests\FileSearchStores\Documents;
+
+use Gemini\Enums\Method;
+use Gemini\Foundation\Request;
+
+/**
+ * @link https://ai.google.dev/api/file-search/documents#method:-fileSearchStores.documents.get
+ */
+class GetRequest extends Request
+{
+    protected Method $method = Method::GET;
+
+    public function __construct(
+        protected readonly string $name,
+    ) {}
+
+    public function resolveEndpoint(): string
+    {
+        return $this->name;
+    }
+}