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

Context caching API for improved performance with long context.

Context caching allows you to cache large amounts of content (code, documents)
for reuse across multiple requests, reducing latency and cost.

## Usage

    # Create a cached context
    {:ok, cache} = Gemini.APIs.ContextCache.create(
      [%Gemini.Types.Content{role: "user", parts: [%{text: large_content}]}],
      display_name: "My Codebase",
      model: "gemini-2.5-flash"
    )

    # Use cached context in requests
    {:ok, response} = Gemini.generate("Analyze this code",
      cached_content: cache.name
    )

    # Delete when done
    :ok = Gemini.APIs.ContextCache.delete(cache.name)

## API Endpoints

- `POST /cachedContents` - Create cached content
- `GET /cachedContents` - List cached contents
- `GET /cachedContents/{name}` - Get specific cache
- `PATCH /cachedContents/{name}` - Update cache TTL
- `DELETE /cachedContents/{name}` - Delete cache

# `cache_opts`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/apis/context_cache.ex#L44)

```elixir
@type cache_opts() :: [
  display_name: String.t(),
  model: String.t(),
  ttl: non_neg_integer(),
  expire_time: DateTime.t(),
  system_instruction: String.t() | Gemini.Types.Content.t(),
  tools: [Altar.ADM.FunctionDeclaration.t()],
  tool_config: Altar.ADM.ToolConfig.t(),
  kms_key_name: String.t(),
  auth: :gemini | :vertex_ai,
  project_id: String.t(),
  location: String.t()
]
```

# `cached_content`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/apis/context_cache.ex#L58)

```elixir
@type cached_content() :: %{
  name: String.t(),
  display_name: String.t() | nil,
  model: String.t(),
  create_time: String.t() | nil,
  update_time: String.t() | nil,
  expire_time: String.t() | nil,
  usage_metadata: Gemini.Types.CachedContentUsageMetadata.t() | nil
}
```

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

```elixir
@spec create([Gemini.Types.Content.t()] | [map()] | String.t(), cache_opts()) ::
  {:ok, cached_content()} | {:error, term()}
```

Create a new cached content.

## Parameters

- `contents`: List of Content structs to cache
- `opts`: Options including:
  - `:display_name` - Human-readable name (required)
  - `:model` - Model to use (default: default model)
  - `:ttl` - Time to live in seconds (default: 3600)
  - `:expire_time` - Specific expiration DateTime

## Returns

- `{:ok, cached_content}` - Created cache metadata
- `{:error, reason}` - Failed to create cache

## Examples

    {:ok, cache} = ContextCache.create(
      [Content.text("Large document content...")],
      display_name: "My Document",
      model: "gemini-2.5-flash",
      ttl: 7200
    )

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

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

Delete a cached content.

## Parameters

- `name`: Cache name to delete
- `opts`: Request options

## Returns

- `:ok` - Successfully deleted
- `{:error, reason}` - Failed to delete

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

```elixir
@spec get(
  String.t(),
  keyword()
) :: {:ok, cached_content()} | {:error, term()}
```

Get a specific cached content by name.

## Parameters

- `name`: Cache name (format: "cachedContents/{id}")
- `opts`: Request options

## Returns

- `{:ok, cached_content}` - Cache metadata
- `{:error, reason}` - Failed to get cache

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

```elixir
@spec list(keyword()) :: {:ok, map()} | {:error, term()}
```

List all cached contents.

## Parameters

- `opts`: Options including:
  - `:page_size` - Number of results per page
  - `:page_token` - Pagination token

## Returns

- `{:ok, %{cached_contents: [cached_content()], next_page_token: String.t() | nil}}`
- `{:error, reason}`

# `update`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/apis/context_cache.ex#L228)

```elixir
@spec update(
  String.t(),
  keyword()
) :: {:ok, cached_content()} | {:error, term()}
```

Update cache TTL.

## Parameters

- `name`: Cache name
- `opts`: Options including:
  - `:ttl` - New TTL in seconds
  - `:expire_time` - New expiration DateTime

## Returns

- `{:ok, cached_content}` - Updated cache metadata
- `{:error, reason}` - Failed to update

---

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