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

Documents API for RAG (Retrieval-Augmented Generation) document management.

Documents are stored in RAG stores and used for semantic search and
context augmentation in generation requests.

## Overview

The Documents API allows you to:
- List documents in a RAG store
- Get document metadata
- Delete documents

## Example Workflow

    # List documents in a store
    {:ok, response} = Gemini.APIs.Documents.list("ragStores/my-store")

    Enum.each(response.documents, fn doc ->
      IO.puts("#{doc.name}: #{doc.state}")
    end)

    # Get specific document
    {:ok, doc} = Gemini.APIs.Documents.get("ragStores/my-store/documents/doc123")

    if Document.active?(doc) do
      IO.puts("Document ready: #{doc.chunk_count} chunks")
    end

    # Delete document
    :ok = Gemini.APIs.Documents.delete("ragStores/my-store/documents/doc123")

## RAG Store Integration

Documents are typically created by uploading files to a RAG store
via the FileSearchStores API. This API focuses on document management
after creation.

# `document_opts`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/apis/documents.ex#L54)

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

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

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

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

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

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

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

Delete a document from a RAG store.

## Parameters

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

## Examples

    :ok = Gemini.APIs.Documents.delete("ragStores/my-store/documents/doc123")

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

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

Get a document by name.

## Parameters

- `name` - Document resource name (e.g., "ragStores/abc/documents/xyz")
- `opts` - Options

## Examples

    {:ok, doc} = Gemini.APIs.Documents.get("ragStores/my-store/documents/doc123")
    IO.puts("State: #{doc.state}")
    IO.puts("Size: #{doc.size_bytes} bytes")
    IO.puts("Chunks: #{doc.chunk_count}")

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

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

List documents in a RAG store.

## Parameters

- `store_name` - RAG store resource name (e.g., "ragStores/abc")
- `opts` - List options

## Options

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

## Examples

    # List all documents
    {:ok, response} = Gemini.APIs.Documents.list("ragStores/my-store")

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

    # With pagination
    {:ok, page1} = Gemini.APIs.Documents.list("ragStores/my-store", page_size: 10)
    if ListDocumentsResponse.has_more_pages?(page1) do
      {:ok, page2} = Gemini.APIs.Documents.list("ragStores/my-store",
        page_token: page1.next_page_token
      )
    end

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

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

List all documents across all pages.

Automatically handles pagination to retrieve all documents.

## Parameters

- `store_name` - RAG store resource name
- `opts` - Options

## Examples

    {:ok, all_docs} = Gemini.APIs.Documents.list_all("ragStores/my-store")
    active = Enum.filter(all_docs, &Document.active?/1)
    IO.puts("Active documents: #{length(active)}")

# `wait_for_processing`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/apis/documents.ex#L203)

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

Wait for a document to finish processing.

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

## Parameters

- `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 `fn(Document.t()) -> any()`

## Examples

    {:ok, doc} = Gemini.APIs.Documents.wait_for_processing(
      "ragStores/my-store/documents/doc123",
      poll_interval: 5000,
      on_status: fn d -> IO.puts("State: #{d.state}") end
    )

    if Document.active?(doc) do
      IO.puts("Document ready with #{doc.chunk_count} chunks")
    end

---

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