Module: GeminiCache

Defined in:
lib/gemini_cache.rb,
lib/gemini_cache/api_client.rb,
lib/gemini_cache/configuration.rb

Overview

Module for interacting with Google’s Gemini API cached contents

Examples:

Basic usage

GeminiCache.configure do |config|
  config.api_key = 'your-api-key'
end

# Create a cache from text
cache = GeminiCache.create_from_text(
  text: "Hello, world!",
  display_name: "my-cache"
)

Defined Under Namespace

Classes: ApiClient, Configuration, Error

Class Method Summary collapse

Class Method Details

.configuration ⇒ Configuration

Returns current configuration.

Returns:



20
21
22
 
# File 'lib/gemini_cache/configuration.rb', line 20

def configuration
  @configuration ||= Configuration.new
end

.configure {|Configuration| ... } ⇒ Object

Configures GeminiCache

Examples:

GeminiCache.configure do |config|
  config.api_key = 'your-api-key'
  config.default_ttl = 600
end

Yields:



31
32
33
 
# File 'lib/gemini_cache/configuration.rb', line 31

def configure
  yield(configuration)
end

.create(parts:, display_name:, on_conflict: :raise_error, model: nil, ttl: nil) ⇒ Hash

Creates a new cache in the Gemini API

Parameters:

  • parts (Array<Hash>) —

    content parts to cache

  • display_name (String) —

    unique display name for the cache

  • on_conflict (:raise_error, :get_existing) (defaults to: :raise_error) —

    action to take if cache exists

  • model (String, nil) (defaults to: nil) —

    Gemini model to use

  • ttl (Integer, nil) (defaults to: nil) —

    time-to-live in seconds

Returns:

  • (Hash) —

    created cache data

Raises:

  • (Error) —

    if cache already exists and on_conflict is :raise_error



61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
 
# File 'lib/gemini_cache.rb', line 61

def create(parts:, display_name:, on_conflict: :raise_error, model: nil, ttl: nil)
  existing_cache = find_by_display_name(display_name:)
  
  if existing_cache
    case on_conflict
    when :raise_error
      raise Error, "Cache with display name '#{display_name}' already exists"
    when :get_existing
      return existing_cache
    end
  end

  content = {
    model: "models/#{model || configuration.default_model}",
    display_name: display_name,
    contents: [{ parts:, role: 'user' }],
    ttl: "#{ttl || configuration.default_ttl}s"
  }

  response = api_client.create_cache(content.to_json)
  find_by_name(name: response['name'])
end

.create_from_local_file(path:, mime_type:, **options) ⇒ Hash

Creates a cache from a local file

Parameters:

  • path (String) —

    path to the local file

  • mime_type (String) —

    MIME type of the file

  • options (Hash) —

    additional options passed to #create

Returns:

  • (Hash) —

    created cache data



105
106
107
108
 
# File 'lib/gemini_cache.rb', line 105

def create_from_local_file(path:, mime_type:, **options)
  file_data = read_local_file(path: path, mime_type: mime_type)
  create(parts: [file_data], **options)
end

.create_from_remote_file(url:, mime_type:, **options) ⇒ Hash

Creates a cache from a remote file

Parameters:

  • url (String) —

    URL of the remote file

  • mime_type (String) —

    MIME type of the file

  • options (Hash) —

    additional options passed to #create

Returns:

  • (Hash) —

    created cache data



115
116
117
118
 
# File 'lib/gemini_cache.rb', line 115

def create_from_remote_file(url:, mime_type:, **options)
  file_data = read_remote_file(url: url, mime_type: mime_type)
  create(parts: [file_data], **options)
end

.create_from_text(text:, **options) ⇒ Hash

Creates a cache from plain text

Parameters:

  • text (String) —

    text content to cache

  • options (Hash) —

    additional options passed to #create

Returns:

  • (Hash) —

    created cache data



88
89
90
 
# File 'lib/gemini_cache.rb', line 88

def create_from_text(text:, **options)
  create(parts: [{ text: }], **options)
end

.create_from_webpage(url:, **options) ⇒ Hash

Creates a cache from a webpage’s content

Parameters:

  • url (String) —

    URL of the webpage

  • options (Hash) —

    additional options passed to #create

Returns:

  • (Hash) —

    created cache data



96
97
98
 
# File 'lib/gemini_cache.rb', line 96

def create_from_webpage(url:, **options)
  create_from_text(text: read_html(url:).inner_text, **options)
end

.delete(name:) ⇒ Boolean

Deletes a specific cache

Parameters:

  • name (String) —

    internal name of the cache to delete

Returns:

  • (Boolean) —

    true if successful



154
155
156
157
 
# File 'lib/gemini_cache.rb', line 154

def delete(name:)
  api_client.delete_cache(name)
  true
end

.delete_all ⇒ void Also known as: clear

This method returns an undefined value.

Deletes all caches



161
162
163
 
# File 'lib/gemini_cache.rb', line 161

def delete_all
  list.each { |item| item.delete }
end

.find_by_display_name(display_name:) ⇒ Hash?

Finds a cache by its display name

Parameters:

  • display_name (String) —

    display name of the cache

Returns:

  • (Hash, nil) —

    cache data if found, nil otherwise



139
140
141
 
# File 'lib/gemini_cache.rb', line 139

def find_by_display_name(display_name:)
  list.find { |item| item['displayName'].eql?(display_name) }
end

.find_by_name(name:) ⇒ Hash?

Finds a cache by its internal name

Parameters:

  • name (String) —

    internal name of the cache

Returns:

  • (Hash, nil) —

    cache data if found, nil otherwise



132
133
134
 
# File 'lib/gemini_cache.rb', line 132

def find_by_name(name:)
  list.find { |item| item['name'].eql?(name) }
end

.list ⇒ Array<Hash>

Lists all available caches

Returns:

  • (Array<Hash>) —

    list of caches with ItemExtender mixed in



122
123
124
125
126
127
 
# File 'lib/gemini_cache.rb', line 122

def list
  response = api_client.list_caches
  return [] if response.empty?

  response['cachedContents'].map { |item| item.extend(ItemExtender) }
end

.read_html(url:, default_remover: true) ⇒ Nokogiri::HTML::Document

Reads and parses HTML content from a URL

Parameters:

  • url (String) —

    URL of the webpage

  • default_remover (Boolean) (defaults to: true) —

    whether to remove script and style tags

Returns:

  • (Nokogiri::HTML::Document) —

    parsed HTML document



47
48
49
50
51
 
# File 'lib/gemini_cache.rb', line 47

def read_html(url:, default_remover: true)
  doc = Nokogiri::HTML(URI.open(url))
  %w[script style].each { |element| doc.css(element).each(&:remove) } if default_remover
  doc
end

.read_local_file(path:, mime_type:) ⇒ Hash

Reads a local file and prepares it for the Gemini API

Parameters:

  • path (String) —

    path to the local file

  • mime_type (String) —

    MIME type of the file

Returns:

  • (Hash) —

    formatted data for the API



31
32
33
 
# File 'lib/gemini_cache.rb', line 31

def read_local_file(path:, mime_type:)
  { inline_data: { mime_type:, data: Base64.strict_encode64(File.read(path)) } }
end

.read_remote_file(url:, mime_type:) ⇒ Hash

Reads a remote file and prepares it for the Gemini API

Parameters:

  • url (String) —

    URL of the remote file

  • mime_type (String) —

    MIME type of the file

Returns:

  • (Hash) —

    formatted data for the API



39
40
41
 
# File 'lib/gemini_cache.rb', line 39

def read_remote_file(url:, mime_type:)
  { inline_data: { mime_type:, data: Base64.strict_encode64(URI.open(url).read) } }
end

.update(name:, content:) ⇒ Hash

Updates an existing cache

Parameters:

  • name (String) —

    internal name of the cache

  • content (Hash) —

    new content for the cache

Returns:

  • (Hash) —

    updated cache data



147
148
149
 
# File 'lib/gemini_cache.rb', line 147

def update(name:, content:)
  api_client.update_cache(name, content)
end