Gemini.APIs.ContextCache (GeminiEx v0.8.4)

View Source

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.0-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

Summary

Types

cache_opts()
cached_content()

Functions

create(contents, opts \\ [])

Create a new cached content.

delete(name, opts \\ [])

Delete a cached content.

get(name, opts \\ [])

Get a specific cached content by name.

list(opts \\ [])

List all cached contents.

update(name, opts \\ [])

Update cache TTL.

Types

cache_opts()

@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()

@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
}

Functions

create(contents, opts \\ [])

@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.0-flash",
  ttl: 7200
)

delete(name, opts \\ [])

@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(name, opts \\ [])

@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(opts \\ [])

@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(name, opts \\ [])

@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