# `Gemini.APIs.FileSearchStores`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/apis/file_search_stores.ex#L1)

File Search Stores API for semantic search and RAG (Retrieval-Augmented Generation).

File Search Stores enable semantic search over documents using vector embeddings.
They are part of the Vertex AI RAG system and provide powerful document search
capabilities for grounding generation responses.

**Note:** This API is only available through Vertex AI authentication.

## Overview

The File Search Stores API allows you to:
- Create stores for organizing searchable documents
- Import files into stores for indexing
- Upload files directly to stores
- List and manage stores
- Delete stores when no longer needed

## Workflow

1. **Create a Store**: Set up a semantic search store
2. **Import Files**: Add documents to the store
3. **Wait for Processing**: Documents are indexed asynchronously
4. **Use in Generation**: Reference the store for grounded responses

## Example: Basic Store Creation

    alias Gemini.APIs.FileSearchStores
    alias Gemini.Types.CreateFileSearchStoreConfig

    # Create a store
    config = %CreateFileSearchStoreConfig{
      display_name: "Product Documentation",
      description: "Technical documentation for all products"
    }

    {:ok, store} = FileSearchStores.create(config, auth: :vertex_ai)
    IO.puts("Created: #{store.name}")

    # Wait for store to be active
    {:ok, ready_store} = FileSearchStores.wait_for_active(store.name)

    # Import a file that was already uploaded
    {:ok, doc} = FileSearchStores.import_file(
      store.name,
      "files/abc123"
    )

## Example: Upload and Import

    # Upload a file directly to the store
    {:ok, doc} = FileSearchStores.upload_to_store(
      store.name,
      "/path/to/document.pdf",
      display_name: "Product Manual"
    )

    # Wait for document to be processed
    {:ok, ready_doc} = FileSearchStores.wait_for_document(doc.name)

## Example: List and Cleanup

    # List all stores
    {:ok, response} = FileSearchStores.list()

    Enum.each(response.file_search_stores, fn store ->
      IO.puts("#{store.display_name}: #{store.document_count} docs")
    end)

    # Delete a store (requires force: true if it has documents)
    :ok = FileSearchStores.delete("fileSearchStores/abc123", force: true)

## Grounding with File Search

Once documents are indexed, use the store for grounding in generation:

    {:ok, response} = Gemini.generate_content(
      "What are the safety features?",
      tools: [
        %{file_search_stores: ["fileSearchStores/abc123"]}
      ]
    )

## Best Practices

1. **Descriptive Names**: Use clear display names for stores
2. **Wait for Processing**: Always wait for documents to reach `:active` state
3. **Batch Imports**: Import multiple files before using the store
4. **Monitor Size**: Check `document_count` and `total_size_bytes`
5. **Clean Up**: Delete stores when no longer needed to avoid costs

# `create_opts`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/apis/file_search_stores.ex#L107)

```elixir
@type create_opts() :: [{:auth, :gemini | :vertex_ai}]
```

# `delete_opts`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/apis/file_search_stores.ex#L121)

```elixir
@type delete_opts() :: [force: boolean(), auth: :gemini | :vertex_ai]
```

# `import_opts`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/apis/file_search_stores.ex#L126)

```elixir
@type import_opts() :: [{:auth, :gemini | :vertex_ai}]
```

# `list_opts`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/apis/file_search_stores.ex#L115)

```elixir
@type list_opts() :: [
  page_size: pos_integer(),
  page_token: String.t(),
  auth: :gemini | :vertex_ai
]
```

# `store_opts`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/apis/file_search_stores.ex#L111)

```elixir
@type store_opts() :: [{:auth, :gemini | :vertex_ai}]
```

# `upload_opts`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/apis/file_search_stores.ex#L130)

```elixir
@type upload_opts() :: [
  display_name: String.t(),
  mime_type: String.t(),
  auth: :gemini | :vertex_ai
]
```

# `wait_doc_opts`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/apis/file_search_stores.ex#L143)

```elixir
@type wait_doc_opts() :: [
  poll_interval: pos_integer(),
  timeout: pos_integer(),
  on_status: (Gemini.Types.FileSearchDocument.t() -> any()),
  auth: :gemini | :vertex_ai
]
```

# `wait_opts`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/apis/file_search_stores.ex#L136)

```elixir
@type wait_opts() :: [
  poll_interval: pos_integer(),
  timeout: pos_integer(),
  on_status: (Gemini.Types.FileSearchStore.t() -> any()),
  auth: :gemini | :vertex_ai
]
```

# `create`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/apis/file_search_stores.ex#L176)

```elixir
@spec create(Gemini.Types.CreateFileSearchStoreConfig.t(), create_opts()) ::
  {:ok, Gemini.Types.FileSearchStore.t()} | {:error, term()}
```

Create a new file search store.

Creates a semantic search store for organizing and searching documents.
The store will be in `:creating` state initially and will transition to
`:active` once ready.

## Parameters

- `config` - CreateFileSearchStoreConfig struct with store configuration
- `opts` - Options (must include `auth: :vertex_ai`)

## Examples

    config = %CreateFileSearchStoreConfig{
      display_name: "Product Docs",
      description: "All product documentation"
    }

    {:ok, store} = FileSearchStores.create(config, auth: :vertex_ai)

    # Wait for it to be active
    {:ok, active_store} = FileSearchStores.wait_for_active(store.name)

# `delete`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/apis/file_search_stores.ex#L239)

```elixir
@spec delete(String.t(), delete_opts()) :: :ok | {:error, term()}
```

Delete a file search store.

By default, stores with documents cannot be deleted. Use `force: true` to
delete a store and all its documents.

## Parameters

- `name` - Store resource name
- `opts` - Delete options

## Options

- `:force` - Delete even if store contains documents (default: false)
- `:auth` - Authentication strategy

## Examples

    # Delete empty store
    :ok = FileSearchStores.delete("fileSearchStores/abc123")

    # Force delete store with documents
    :ok = FileSearchStores.delete(
      "fileSearchStores/abc123",
      force: true
    )

# `get`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/apis/file_search_stores.ex#L202)

```elixir
@spec get(String.t(), store_opts()) ::
  {:ok, Gemini.Types.FileSearchStore.t()} | {:error, term()}
```

Get a file search store by name.

## Parameters

- `name` - Store resource name (e.g., "fileSearchStores/abc123")
- `opts` - Options

## Examples

    {:ok, store} = FileSearchStores.get("fileSearchStores/abc123")
    IO.puts("State: #{store.state}")
    IO.puts("Documents: #{store.document_count}")
    IO.puts("Size: #{store.total_size_bytes} bytes")

# `get_document`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/apis/file_search_stores.ex#L483)

```elixir
@spec get_document(String.t(), store_opts()) ::
  {:ok, Gemini.Types.FileSearchDocument.t()} | {:error, term()}
```

Get a document from a file search store.

## Parameters

- `document_name` - Document resource name
- `opts` - Options

## Examples

    {:ok, doc} = FileSearchStores.get_document(
      "fileSearchStores/abc/documents/xyz"
    )
    IO.puts("State: #{doc.state}")

# `import_file`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/apis/file_search_stores.ex#L337)

```elixir
@spec import_file(String.t(), String.t(), import_opts()) ::
  {:ok, Gemini.Types.FileSearchDocument.t()} | {:error, term()}
```

Import an already uploaded file into the store.

The file must have been previously uploaded using the Files API.
This creates a document in the store that will be indexed for search.

## Parameters

- `store_name` - Store resource name
- `file_name` - File resource name (e.g., "files/abc123")
- `opts` - Options

## Examples

    # Upload a file first with the Gemini Files API
    {:ok, file} = Gemini.APIs.Files.upload("/path/to/doc.pdf", auth: :gemini)

    # Import it into the store
    {:ok, doc} = FileSearchStores.import_file(
      "fileSearchStores/abc123",
      file.name,
      auth: :vertex_ai
    )

    # Wait for processing
    {:ok, ready_doc} = FileSearchStores.wait_for_document(doc.name, auth: :vertex_ai)

# `list`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/apis/file_search_stores.ex#L279)

```elixir
@spec list(list_opts()) ::
  {:ok, Gemini.Types.ListFileSearchStoresResponse.t()} | {:error, term()}
```

List file search stores.

## Parameters

- `opts` - List options

## Options

- `:page_size` - Number of stores per page (default: 100)
- `:page_token` - Token from previous response for pagination
- `:auth` - Authentication strategy

## Examples

    # List all stores
    {:ok, response} = FileSearchStores.list()

    Enum.each(response.file_search_stores, fn store ->
      IO.puts("#{store.display_name}: #{store.state}")
    end)

    # With pagination
    {:ok, page1} = FileSearchStores.list(page_size: 10)
    if ListFileSearchStoresResponse.has_more_pages?(page1) do
      {:ok, page2} = FileSearchStores.list(
        page_token: page1.next_page_token
      )
    end

# `list_all`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/apis/file_search_stores.ex#L304)

```elixir
@spec list_all(list_opts()) ::
  {:ok, [Gemini.Types.FileSearchStore.t()]} | {:error, term()}
```

List all file search stores across all pages.

Automatically handles pagination to retrieve all stores.

## Parameters

- `opts` - Options

## Examples

    {:ok, all_stores} = FileSearchStores.list_all()
    active = Enum.filter(all_stores, &FileSearchStore.active?/1)
    IO.puts("Active stores: #{length(active)}")

# `upload_to_store`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/apis/file_search_stores.ex#L377)

```elixir
@spec upload_to_store(String.t(), String.t(), upload_opts()) ::
  {:ok, Gemini.Types.FileSearchDocument.t()} | {:error, term()}
```

Upload a file directly to the store.

This is a convenience method that uploads a file and imports it into the
store in a single operation.

## Parameters

- `store_name` - Store resource name
- `file_path` - Path to local file
- `opts` - Upload options

## Options

- `:display_name` - Human-readable name for the document
- `:mime_type` - MIME type (auto-detected if not provided)
- `:auth` - Authentication strategy

## Examples

    {:ok, doc} = FileSearchStores.upload_to_store(
      "fileSearchStores/abc123",
      "/path/to/document.pdf",
      display_name: "Product Manual v2.0"
    )

    IO.puts("Uploaded: #{doc.name}")

# `wait_for_active`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/apis/file_search_stores.ex#L420)

```elixir
@spec wait_for_active(String.t(), wait_opts()) ::
  {:ok, Gemini.Types.FileSearchStore.t()} | {:error, term()}
```

Wait for a store to become active.

Polls the store status until it reaches `:active` or `:failed` state.

## Parameters

- `name` - Store resource name
- `opts` - Wait options

## Options

- `:poll_interval` - Milliseconds between status checks (default: 2000)
- `:timeout` - Maximum wait time in milliseconds (default: 300000 = 5 min)
- `:on_status` - Callback for status updates `fn(FileSearchStore.t()) -> any()`
- `:auth` - Authentication strategy

## Examples

    {:ok, store} = FileSearchStores.wait_for_active(
      "fileSearchStores/abc123",
      poll_interval: 5000,
      on_status: fn s -> IO.puts("State: #{s.state}") end
    )

    if FileSearchStore.active?(store) do
      IO.puts("Store ready!")
    end

# `wait_for_document`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/apis/file_search_stores.ex#L456)

```elixir
@spec wait_for_document(String.t(), wait_doc_opts()) ::
  {:ok, Gemini.Types.FileSearchDocument.t()} | {:error, term()}
```

Wait for a document to finish processing.

Polls the document status until it reaches `:active` or `:failed` state.

## Parameters

- `document_name` - Document resource name
- `opts` - Wait options

## Options

- `:poll_interval` - Milliseconds between status checks (default: 2000)
- `:timeout` - Maximum wait time in milliseconds (default: 300000 = 5 min)
- `:on_status` - Callback for status updates
- `:auth` - Authentication strategy

## Examples

    {:ok, doc} = FileSearchStores.wait_for_document(
      "fileSearchStores/abc/documents/xyz",
      on_status: fn d -> IO.puts("Chunks: #{d.chunk_count}") end
    )

---

*Consult [api-reference.md](api-reference.md) for complete listing*