gemini_cache 0.0.9 → 0.0.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ae4847ce3abf808c2779601462af28a47989301593355a8a39977a5df495f322
-  data.tar.gz: 71e72d0e2750d6b530d407f97a7490c65b6acbf342ad10803916b4b24d418b71
+  metadata.gz: 5f3682e46bf67ce3fae20c5e27210eafdadc25338a54eecfec4c9f48a726ce7a
+  data.tar.gz: '0393aa11b0f296e72cbd7604be9061ad0186df90cfaeb6d5665b4d77d893d700'
 SHA512:
-  metadata.gz: 8ab29a93e9555626f6d1eecb189351b5d62b28805e0e90e0ba9c29cb9e5bcf8698f72dadb0621ffbf196503d186a2c341b45c387bc25f940d055bb110455ff78
-  data.tar.gz: 50a917b60662ecd5bc1cef90c0a633febfcfbe294c297525d397f60863dfaa29977e43c0743c9f717452fa7d45ce5fe2da8f11f3816d0f65fa5e06f6632675ff
+  metadata.gz: 5caf764b56efeb6234a03248b9dca22d7f84d2a885e7dca10651b80c49c2c390f473db4cd92037965af2f2ee3718cc78565db2bb257963b8137a9504056590ea
+  data.tar.gz: fba129ed606d3c62a5f39149cd2359fd5d6c18d01a978ffee0bff4a3968fc2c9f2f49723ffe6421192399b021e0023d9766fc7601ebf321e9619ea2b54a77834

data/README.md

@@ -0,0 +1,145 @@
+# GeminiCache
+
+GeminiCache é uma biblioteca Ruby para interagir com a API de Cache do Google Gemini. Ela fornece uma interface simples para criar, gerenciar e manipular caches de conteúdo para uso com os modelos de IA do Gemini.
+
+## Instalação
+
+Adicione esta linha ao Gemfile da sua aplicação:
+
+```ruby
+gem 'gemini_cache'
+```
+
+E então execute:
+
+```bash
+$ bundle install
+```
+
+Ou instale manualmente:
+
+```bash
+$ gem install gemini_cache
+```
+
+## Configuração
+
+Antes de usar a biblioteca, você precisa configurar sua chave de API do Google Gemini. Você pode fazer isso de duas maneiras:
+
+### 1. Usando variáveis de ambiente
+
+```bash
+export GEMINI_API_KEY='sua_chave_api_aqui'
+```
+
+### 2. Usando o bloco de configuração
+
+```ruby
+GeminiCache.configure do |config|
+  config.api_key = 'sua_chave_api_aqui'
+  config.timeout = 30 # opcional, tempo limite em segundos
+  config.cache_dir = '/path/to/cache' # opcional, diretório para cache local
+end
+```
+
+## Uso Básico
+
+### Inicializando o Cliente
+
+```ruby
+cache = GeminiCache::Client.new
+```
+
+### Operações Básicas
+
+#### Armazenando dados no cache
+
+```ruby
+# Armazena um valor com uma chave
+cache.set('minha_chave', 'meu_valor')
+
+# Armazena com tempo de expiração (em segundos)
+cache.set('minha_chave', 'meu_valor', expires_in: 3600)
+```
+
+#### Recuperando dados do cache
+
+```ruby
+# Recupera um valor
+valor = cache.get('minha_chave')
+
+# Recupera com valor padrão se a chave não existir
+valor = cache.get('minha_chave', default: 'valor_padrao')
+```
+
+#### Removendo dados do cache
+
+```ruby
+# Remove uma chave específica
+cache.delete('minha_chave')
+
+# Limpa todo o cache
+cache.clear
+```
+
+### Uso Avançado
+
+#### Cache em Lote
+
+```ruby
+# Armazena múltiplos valores
+cache.set_multi({
+  'chave1' => 'valor1',
+  'chave2' => 'valor2'
+})
+
+# Recupera múltiplos valores
+valores = cache.get_multi(['chave1', 'chave2'])
+```
+
+#### Cache com Blocos
+
+```ruby
+# Executa o bloco apenas se o valor não estiver em cache
+resultado = cache.fetch('minha_chave') do
+  # código computacionalmente intensivo aqui
+  resultado_computado
+end
+```
+
+## Exemplos de Uso com Gemini AI
+
+```ruby
+# Cacheia resultados de chamadas à API do Gemini
+resposta = cache.fetch('consulta_gemini') do
+  gemini_client.generate_content('Qual é o sentido da vida?')
+end
+
+# Cache com namespace para diferentes modelos
+cache_pro = GeminiCache::Client.new(namespace: 'gemini-pro')
+cache_vision = GeminiCache::Client.new(namespace: 'gemini-vision')
+```
+
+## Tratamento de Erros
+
+```ruby
+begin
+  cache.get('minha_chave')
+rescue GeminiCache::ConnectionError => e
+  puts "Erro de conexão: #{e.message}"
+rescue GeminiCache::TimeoutError => e
+  puts "Tempo limite excedido: #{e.message}"
+end
+```
+
+## Contribuindo
+
+1. Faça um fork do projeto
+2. Crie sua feature branch (`git checkout -b feature/nova-feature`)
+3. Faça commit das suas alterações (`git commit -am 'Adiciona nova feature'`)
+4. Faça push para a branch (`git push origin feature/nova-feature`)
+5. Crie um novo Pull Request
+
+## Licença
+
+Esta gem está disponível como código aberto sob os termos da [Licença MIT](https://opensource.org/licenses/MIT).

data/lib/gemini_cache/api_client.rb

@@ -0,0 +1,86 @@
+module GeminiCache
+  # Client for making HTTP requests to the Gemini API
+  class ApiClient
+    # Error class for API-related errors
+    class ApiError < StandardError; end
+
+    # Initializes a new API client
+    def initialize
+      @conn = Faraday.new(
+        url: GeminiCache.configuration.api_base_url,
+        headers: { 'Content-Type' => 'application/json' }
+      )
+    end
+
+    # Creates a new cache
+    # @param content [String] JSON string of cache content
+    # @return [Hash] API response
+    # @raise [ApiError] if the request fails
+    def create_cache(content)
+      response = @conn.post('/v1beta/cachedContents') do |req|
+        req.params['key'] = api_key
+        req.body = content
+      end
+
+      handle_response(response)
+    end
+
+    # Lists all caches
+    # @return [Hash] API response
+    # @raise [ApiError] if the request fails
+    def list_caches
+      response = @conn.get('/v1beta/cachedContents') do |req|
+        req.params['key'] = api_key
+      end
+
+      handle_response(response)
+    end
+
+    # Updates an existing cache
+    # @param name [String] cache name
+    # @param content [String] JSON string of new content
+    # @return [Hash] API response
+    # @raise [ApiError] if the request fails
+    def update_cache(name, content)
+      response = @conn.patch("/v1beta/#{name}") do |req|
+        req.params['key'] = api_key
+        req.body = content
+      end
+
+      handle_response(response)
+    end
+
+    # Deletes a cache
+    # @param name [String] cache name
+    # @return [Hash] API response
+    # @raise [ApiError] if the request fails
+    def delete_cache(name)
+      response = @conn.delete("/v1beta/#{name}") do |req|
+        req.params['key'] = api_key
+      end
+
+      handle_response(response)
+    end
+
+    private
+
+    # Gets the API key from configuration or environment
+    # @return [String] API key
+    def api_key
+      GeminiCache.configuration.api_key || ENV.fetch('GEMINI_API_KEY')
+    end
+
+    # Handles API responses
+    # @param response [Faraday::Response] HTTP response
+    # @return [Hash] parsed response body
+    # @raise [ApiError] if response status is not 200
+    def handle_response(response)
+      return JSON.parse(response.body) if response.status == 200
+      
+      error_message = JSON.parse(response.body)['error'] rescue response.body
+      raise ApiError, "API request failed (#{response.status}): #{error_message}"
+    rescue Faraday::Error => e
+      raise ApiError, "Network error: #{e.message}"
+    end
+  end
+end 

data/lib/gemini_cache/configuration.rb

@@ -0,0 +1,35 @@
+module GeminiCache
+  # Configuration class for GeminiCache settings
+  # @attr [String] api_key The API key for Gemini API
+  # @attr [String] api_base_url The base URL for the Gemini API
+  # @attr [String] default_model The default model to use
+  # @attr [Integer] default_ttl The default time-to-live in seconds
+  class Configuration
+    attr_accessor :api_key, :api_base_url, :default_model, :default_ttl
+
+    # Initializes a new Configuration with default values
+    def initialize
+      @api_base_url = 'https://generativelanguage.googleapis.com'
+      @default_model = 'gemini-1.5-flash-8b'
+      @default_ttl = 300
+    end
+  end
+
+  class << self
+    # @return [Configuration] current configuration
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Configures GeminiCache
+    # @yield [Configuration] configuration object
+    # @example
+    #   GeminiCache.configure do |config|
+    #     config.api_key = 'your-api-key'
+    #     config.default_ttl = 600
+    #   end
+    def configure
+      yield(configuration)
+    end
+  end
+end 

data/lib/gemini_cache/item_extender.rb

@@ -1,46 +1,89 @@
+# frozen_string_literal: true
+
 module ItemExtender
-  def delete = GeminiCache.delete(name: self['name'])
+  GEMINI_API_BASE_URL = 'https://generativelanguage.googleapis.com'
+  DEFAULT_TIMEOUT = 300 # seconds
+  ACCURATE_MODE_CONFIG = { temperature: 0, topP: 0, topK: 1 }.freeze
 
-  def ttl=(new_ttl)
-    GeminiCache.update(name: self['name'], content: { ttl: "#{new_ttl}s" })
-    GeminiCache.get_by_name(name: self['name'])
+  # Deletes the cached item
+  # @return [void]
+  def delete
+    GeminiCache.delete(name: self['name'])
   end
 
+  # Updates the TTL of the cached item
+  # @param new_ttl [Integer] new TTL value in seconds
+  # @return [void]
+  def ttl=(new_ttl)
+    GeminiCache.update(name: self['name'], content: { ttl: "#{new_ttl}s" }.to_json)
+  end
+  
+  # Generates content using the Gemini API
+  # @param contents [Array<Hash>] array of content parts
+  # @param generation_config [Hash, nil] optional generation configuration
+  # @return [Hash] response with added #content method
+  # @raise [GeminiAPIError] when the API request fails
   def generate_content(contents:, generation_config: nil)
-    conn = Faraday.new(
-      url: 'https://generativelanguage.googleapis.com',
+    response = api_client.post(generate_content_endpoint) do |req|
+      req.params['key'] = ENV.fetch('GEMINI_API_KEY')
+      req.body = build_request_body(contents, generation_config)
+    end
+    
+    handle_response(response)
+  rescue Faraday::Error => e
+    raise GeminiAPIError, "Request failed: #{e.message}"
+  end
+    
+  # Generates content from a single prompt
+  # @param prompt [String] the input prompt
+  # @param generation_config [Hash, Symbol] generation configuration or :accurate_mode
+  # @return [String] generated content
+  def single_prompt(prompt:, generation_config: :accurate_mode)
+    config = generation_config.eql?(:accurate_mode) ? ACCURATE_MODE_CONFIG : generation_config
+    
+    generate_content(
+      contents: [{ parts: [{ text: prompt }], role: 'user' }],
+      generation_config: config
+    ).content
+  end
+  
+  private
+
+  def api_client
+    @api_client ||= Faraday.new(
+      url: GEMINI_API_BASE_URL,
       headers: { 'Content-Type' => 'application/json' }
     ) do |f|
-      f.options.timeout = 300        # timeout em segundos para a requisição completa
-      f.options.open_timeout = 300   # timeout em segundos para abrir a conexão
+      f.options.timeout = DEFAULT_TIMEOUT
+      f.options.open_timeout = DEFAULT_TIMEOUT
     end
+  end
+
+  def generate_content_endpoint
+    "/v1beta/models/#{self['model'].split('/').last}:generateContent"
+  end
 
-    body = {
+  def build_request_body(contents, generation_config)
+    {
       cached_content: self['name'],
-      contents:
-    }
+      contents: contents,
+      generation_config: generation_config
+    }.compact.to_json
+  end
 
-    body[:generation_config] = generation_config if !generation_config.nil?
+  def handle_response(response)
+    return parse_successful_response(response) if response.status == 200
 
-    response = conn.post("/v1beta/models/#{self['model'].split('/').last}:generateContent") do |req|
-      req.params['key'] = ENV.fetch('GEMINI_API_KEY')
-      req.body = body.to_json
-    end
-    
-    if response.status == 200
-      resp = JSON.parse(response.body)
-      def resp.content = dig('candidates', 0, 'content', 'parts', 0, 'text')
-      return resp
-    end
+    raise GeminiAPIError, "Content generation failed: #{response.body}"
+  end
 
-    raise "Erro ao gerar conteúdo: #{response.body}"
-  rescue Faraday::Error => e
-    raise "Erro na requisição: #{e.message}"
+  def parse_successful_response(response)
+    resp = JSON.parse(response.body)
+    def resp.content
+      dig('candidates', 0, 'content', 'parts', 0, 'text')
+    end
+    resp
   end
-    
-  def single_prompt(prompt:, generation_config: :accurate_mode)
-    # accurate_mode: less creative, more accurate
-    generation_config = { temperature: 0, topP: 0, topK: 1 } if generation_config.eql?(:accurate_mode)
-    generate_content(contents: [{ parts: [{ text: prompt }], role: 'user' }], generation_config:).content
-  end      
 end
+
+class GeminiAPIError < StandardError; end

data/lib/gemini_cache.rb

@@ -4,122 +4,169 @@ require 'nokogiri'
 require 'json'
 require 'base64'
 
+require 'gemini_cache/configuration'
+require 'gemini_cache/api_client'
 require 'gemini_cache/item_extender'
 
+# Module for interacting with Google's Gemini API cached contents
+# @example 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"
+#   )
 module GeminiCache
-  def self.read_local_file(path:, mime_type:) = { inline_data: { mime_type:, data: Base64.strict_encode64(File.read(path)) } } 
-  def self.read_remote_file(url:, mime_type:) = { inline_data: { mime_type:, data: Base64.strict_encode64(URI.open(url).read) } } 
-  def self.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
+  # Custom error class for GeminiCache-specific errors
+  class Error < StandardError; end
 
-    doc
-  end
-
-  def self.create(parts:, display_name:, model: 'gemini-1.5-flash-8b', ttl: 300)
-    raise "Cache name already exist: '#{display_name}'" if GeminiCache.get_by_display_name(display_name:)
-
-    content = {
-      model: "models/#{model}",
-      display_name:,
-      contents: [parts:, role: 'user'],
-      ttl: "#{ttl}s"
-    }.to_json
-  
-    conn = Faraday.new(
-      url: 'https://generativelanguage.googleapis.com',
-      headers: { 'Content-Type' => 'application/json' }
-    )
-  
-    response = conn.post('/v1beta/cachedContents') do |req|
-      req.params['key'] = ENV.fetch('GEMINI_API_KEY')
-      req.body = content
+  class << self
+    # Reads a local file and prepares it for the Gemini API
+    # @param path [String] path to the local file
+    # @param mime_type [String] MIME type of the file
+    # @return [Hash] formatted data for the API
+    def read_local_file(path:, mime_type:)
+      { inline_data: { mime_type:, data: Base64.strict_encode64(File.read(path)) } }
     end
-  
-    return get_by_name(name: JSON.parse(response.body)['name']) if response.status == 200
-  
-    raise "Erro ao criar cache: #{response.status} - #{response.body}"
-  rescue Faraday::Error => e
-    raise "Erro na requisição: #{e.message}"
-  end
 
-  def self.create_from_text(text:, display_name:, model: 'gemini-1.5-flash-8b', ttl: 300)
-    GeminiCache.create(parts: [{ text: }], display_name:, model:, ttl:)
-  end
+    # Reads a remote file and prepares it for the Gemini API
+    # @param url [String] URL of the remote file
+    # @param mime_type [String] MIME type of the file
+    # @return [Hash] formatted data for the API
+    def read_remote_file(url:, mime_type:)
+      { inline_data: { mime_type:, data: Base64.strict_encode64(URI.open(url).read) } }
+    end
 
-  def self.create_from_webpage(url:, display_name:, model: 'gemini-1.5-flash-8b', ttl: 300)
-    create_from_text(text: GeminiCache.read_html(url:).inner_text, display_name:, model:, ttl:)
-  end
+    # Reads and parses HTML content from a URL
+    # @param url [String] URL of the webpage
+    # @param default_remover [Boolean] whether to remove script and style tags
+    # @return [Nokogiri::HTML::Document] parsed HTML document
+    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
 
-  def self.create_from_local_file(path:, mime_type:, display_name:, model: 'gemini-1.5-flash-8b', ttl: 300)
-    GeminiCache.create(parts: GeminiCache.read_local_file(path:, mime_type:), display_name:, model:, ttl:)
-  end
+    # Creates a new cache in the Gemini API
+    # @param parts [Array<Hash>] content parts to cache
+    # @param display_name [String] unique display name for the cache
+    # @param on_conflict [:raise_error, :get_existing] action to take if cache exists
+    # @param model [String, nil] Gemini model to use
+    # @param ttl [Integer, nil] time-to-live in seconds
+    # @return [Hash] created cache data
+    # @raise [Error] if cache already exists and on_conflict is :raise_error
+    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
 
-  def self.create_from_remote_file(url:, mime_type:, display_name:, model: 'gemini-1.5-flash-8b', ttl: 300)
-    GeminiCache.create(parts: GeminiCache.read_remote_file(url:, mime_type:), display_name:, model:, ttl:)
-  end
+    # Creates a cache from plain text
+    # @param text [String] text content to cache
+    # @param options [Hash] additional options passed to #create
+    # @return [Hash] created cache data
+    def create_from_text(text:, **options)
+      create(parts: [{ text: }], **options)
+    end
 
-  def self.get_by_name(name: nil) = GeminiCache.list.find { |item| item['name'].eql? name }
-  def self.get_by_display_name(display_name: nil) = GeminiCache.list.find { |item| item['displayName'].eql? display_name }
+    # Creates a cache from a webpage's content
+    # @param url [String] URL of the webpage
+    # @param options [Hash] additional options passed to #create
+    # @return [Hash] created cache data
+    def create_from_webpage(url:, **options)
+      create_from_text(text: read_html(url:).inner_text, **options)
+    end
 
-  def self.list
-    conn = Faraday.new(
-      url: 'https://generativelanguage.googleapis.com',
-      headers: { 'Content-Type' => 'application/json' }
-    )
+    # Creates a cache from a local file
+    # @param path [String] path to the local file
+    # @param mime_type [String] MIME type of the file
+    # @param options [Hash] additional options passed to #create
+    # @return [Hash] created cache data
+    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
 
-    response = conn.get("/v1beta/cachedContents") do |req|
-      req.params['key'] = ENV.fetch('GEMINI_API_KEY')
+    # Creates a cache from a remote file
+    # @param url [String] URL of the remote file
+    # @param mime_type [String] MIME type of the file
+    # @param options [Hash] additional options passed to #create
+    # @return [Hash] created cache data
+    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
-    
-    return [] if JSON.parse(response.body).empty?
 
-    JSON.parse(response.body)['cachedContents'].map { |item| item.extend(ItemExtender) }
+    # Lists all available caches
+    # @return [Array<Hash>] list of caches with ItemExtender mixed in
+    def list
+      response = api_client.list_caches
+      return [] if response.empty?
 
-  rescue Faraday::Error => e
-    raise "Erro na requisição: #{e.message}"
-  end
-  
-  def self.update(name:, content:)
-    conn = Faraday.new(
-      url: 'https://generativelanguage.googleapis.com',
-      headers: { 'Content-Type' => 'application/json' }
-    )
-
-    response = conn.patch("/v1beta/#{name}") do |req|
-      req.params['key'] = ENV.fetch('GEMINI_API_KEY')
-      req.body = content.to_json
+      response['cachedContents'].map { |item| item.extend(ItemExtender) }
     end
 
-    return JSON.parse(response.body) if response.status == 200
-    
-    raise "Erro ao atualizar cache: #{response.body}"
-  rescue Faraday::Error => e
-    raise "Erro na requisição: #{e.message}"
-  end
-
-  def self.delete(name:)
-    conn = Faraday.new(
-      url: 'https://generativelanguage.googleapis.com',
-      headers: { 'Content-Type' => 'application/json' }
-    )
+    # Finds a cache by its internal name
+    # @param name [String] internal name of the cache
+    # @return [Hash, nil] cache data if found, nil otherwise
+    def find_by_name(name:)
+      list.find { |item| item['name'].eql?(name) }
+    end
 
-    response = conn.delete("/v1beta/#{name}") do |req|
-      req.params['key'] = ENV.fetch('GEMINI_API_KEY')
+    # Finds a cache by its display name
+    # @param display_name [String] display name of the cache
+    # @return [Hash, nil] cache data if found, nil otherwise
+    def find_by_display_name(display_name:)
+      list.find { |item| item['displayName'].eql?(display_name) }
     end
 
-    return true if response.status == 200
-    
-    raise "Erro ao deletar cache: #{response.body}"
-  rescue Faraday::Error => e
-    raise "Erro na requisição: #{e.message}"
-  end
+    # Updates an existing cache
+    # @param name [String] internal name of the cache
+    # @param content [Hash] new content for the cache
+    # @return [Hash] updated cache data
+    def update(name:, content:)
+      api_client.update_cache(name, content)
+    end
 
-  def self.delete_all
-    GeminiCache.list.each { |item| item.delete }
-  end
+    # Deletes a specific cache
+    # @param name [String] internal name of the cache to delete
+    # @return [Boolean] true if successful
+    def delete(name:)
+      api_client.delete_cache(name)
+      true
+    end
 
-  class << self
+    # Deletes all caches
+    # @return [void]
+    def delete_all
+      list.each { |item| item.delete }
+    end
     alias clear delete_all
+
+    private
+
+    def api_client
+      @api_client ||= ApiClient.new
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gemini_cache
 version: !ruby/object:Gem::Version
-  version: 0.0.9
+  version: 0.0.11
 platform: ruby
 authors:
 - Gedean Dias
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-11-23 00:00:00.000000000 Z
+date: 2024-11-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -58,7 +58,10 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- README.md
 - lib/gemini_cache.rb
+- lib/gemini_cache/api_client.rb
+- lib/gemini_cache/configuration.rb
 - lib/gemini_cache/item_extender.rb
 homepage: https://github.com/gedean/gemini_cache
 licenses: