gemini_cache 0.0.11 → 0.0.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5f3682e46bf67ce3fae20c5e27210eafdadc25338a54eecfec4c9f48a726ce7a
-  data.tar.gz: '0393aa11b0f296e72cbd7604be9061ad0186df90cfaeb6d5665b4d77d893d700'
+  metadata.gz: c7e9a54d31ede523084b82ed3d94912bcbbd33ac2f0452bbc0a87d22ddc3d749
+  data.tar.gz: 7ca621fad09fc18f1a87938d2a42b289841ed7c9a6eaadd290869af4cd132613
 SHA512:
-  metadata.gz: 5caf764b56efeb6234a03248b9dca22d7f84d2a885e7dca10651b80c49c2c390f473db4cd92037965af2f2ee3718cc78565db2bb257963b8137a9504056590ea
-  data.tar.gz: fba129ed606d3c62a5f39149cd2359fd5d6c18d01a978ffee0bff4a3968fc2c9f2f49723ffe6421192399b021e0023d9766fc7601ebf321e9619ea2b54a77834
+  metadata.gz: 7281d91213fa3b6243e6013e352653b89e15c0be1545ad62c11c97f3259f7afcdb673ffd82d9130c3fd61087ef555844ebe35f684c5ebb0ccd1e9fa0a9a65f7f
+  data.tar.gz: 9648a180a9c48e3ddddc52d3006603b9a8b8f418712474311c578660d8c329ceb4ca5ee23f89ab6262eb4058818e2289910dc58979702662852d50aa3ed2a85f

data/README.md

@@ -1,145 +1,153 @@
-# GeminiCache
+# GeminiCache Module Usage Documentation
 
-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.
+## Introduction
+The `GeminiCache` module is a library designed for managing API caches, with features to process web pages, local and remote files, as well as interact with an API to create, update, list, and delete caches. This document describes its functionalities and usage.
 
-## Instalação
+## Requirements
+To use the module, ensure the following Ruby libraries are installed:
 
-Adicione esta linha ao Gemfile da sua aplicação:
+- `faraday`
+- `open-uri`
+- `nokogiri`
+- `json`
+- `base64`
 
-```ruby
-gem 'gemini_cache'
-```
-
-E então execute:
-
-```bash
-$ bundle install
-```
-
-Ou instale manualmente:
-
-```bash
-$ gem install gemini_cache
-```
-
-## Configuração
+## Code Structure
 
-Antes de usar a biblioteca, você precisa configurar sua chave de API do Google Gemini. Você pode fazer isso de duas maneiras:
+The module includes the following components:
 
-### 1. Usando variáveis de ambiente
-
-```bash
-export GEMINI_API_KEY='sua_chave_api_aqui'
-```
+1. **Classes and Modules**:
+   - `GeminiCache::Error`: Class for handling custom errors.
+   - `GeminiCache`: Contains the main methods for cache management and file processing.
 
-### 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
-```
+2. **Dependencies**:
+   - `gemini_cache/configuration`
+   - `gemini_cache/api_client`
+   - `gemini_cache/item_extender`
 
-## Uso Básico
+## Features
 
-### Inicializando o Cliente
+### 1. HTML Parsing
+Allows processing and cleaning the content of a web page.
 
+#### Syntax
 ```ruby
-cache = GeminiCache::Client.new
+GeminiCache.parse_html(url:, default_remover: true)
 ```
+- **Parameters**:
+  - `url`: The URL of the page to process.
+  - `default_remover`: Automatically removes `<script>` and `<style>` elements (default: `true`).
+- **Returns**: A `Nokogiri::HTML` object containing the processed HTML.
 
-### Operações Básicas
-
-#### Armazenando dados no cache
+### 2. File Reading
 
+#### a) Local Files
+Reads a local file and returns its Base64 encoded data.
 ```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)
+GeminiCache.read_local_file(path:, mime_type:)
 ```
+- **Parameters**:
+  - `path`: Path to the file.
+  - `mime_type`: MIME type of the file.
+- **Returns**: Hash containing the encoded data.
 
-#### Recuperando dados do cache
-
+#### b) Remote Files
+Reads a remote file and returns its Base64 encoded data.
 ```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')
+GeminiCache.read_remote_file(url:, mime_type:)
 ```
+- **Parameters**:
+  - `url`: URL of the file.
+  - `mime_type`: MIME type of the file.
+- **Returns**: Hash containing the encoded data.
 
-#### Removendo dados do cache
-
+### 3. Webpage Text Reading
+Extracts text content from a web page, removing unnecessary elements.
 ```ruby
-# Remove uma chave específica
-cache.delete('minha_chave')
-
-# Limpa todo o cache
-cache.clear
+GeminiCache.read_webpage_text(url:, default_remover: true)
 ```
+- **Parameters**:
+  - `url`: URL of the page.
+  - `default_remover`: Automatically removes `<script>` and `<style>` elements (default: `true`).
+- **Returns**: Hash containing the page text.
 
-### Uso Avançado
-
-#### Cache em Lote
+### 4. Cache Creation
+Creates a new cache from different data sources.
 
+#### General Syntax
 ```ruby
-# Armazena múltiplos valores
-cache.set_multi({
-  'chave1' => 'valor1',
-  'chave2' => 'valor2'
-})
-
-# Recupera múltiplos valores
-valores = cache.get_multi(['chave1', 'chave2'])
+GeminiCache.create(parts:, display_name:, on_conflict: :raise_error, model: nil, ttl: nil)
 ```
-
-#### Cache com Blocos
-
+- **Parameters**:
+  - `parts`: Cache data.
+  - `display_name`: Display name of the cache.
+  - `on_conflict`: Action on conflict (`:raise_error` or `:get_existing`).
+  - `model`: Model used (default: system configuration).
+  - `ttl`: Time-to-live for the cache (default: system configuration).
+- **Returns**: The created cache object.
+
+#### Creation Methods
+- Text:
+  ```ruby
+  GeminiCache.create_from_text(text:, **options)
+  ```
+- Web Page:
+  ```ruby
+  GeminiCache.create_from_webpage(url:, **options)
+  ```
+- Local File:
+  ```ruby
+  GeminiCache.create_from_local_file(path:, mime_type:, **options)
+  ```
+- Remote File:
+  ```ruby
+  GeminiCache.create_from_remote_file(url:, mime_type:, **options)
+  ```
+
+### 5. Cache Management
+
+#### Cache Listing
+Lists all available caches.
 ```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
+GeminiCache.list
 ```
-
-## Exemplos de Uso com Gemini AI
-
+- **Returns**: Array of cache objects.
+
+#### Cache Retrieval
+- By Name:
+  ```ruby
+  GeminiCache.find_by_name(name:)
+  ```
+- By Display Name:
+  ```ruby
+  GeminiCache.find_by_display_name(display_name:)
+  ```
+
+#### Cache Updating
+Updates an existing cache.
 ```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')
+GeminiCache.update(name:, content:)
 ```
+- **Parameters**:
+  - `name`: Name of the cache.
+  - `content`: Updated content.
 
-## 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
-```
+#### Cache Deletion
+- By Name:
+  ```ruby
+  GeminiCache.delete(name:)
+  ```
+- All Caches:
+  ```ruby
+  GeminiCache.delete_all
+  ```
 
-## Contribuindo
+## Configuration
+The methods use configurations defined in the `gemini_cache/configuration` module, and communication is handled via `gemini_cache/api_client`.
 
-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
+## Errors
+In case of conflicts or API errors, the module raises a custom exception `GeminiCache::Error`.
 
-## Licença
+## Conclusion
+This documentation covers the main functionalities of the `GeminiCache` module. For more details on specific configurations, refer to the source code or official documentation.
 
-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

@@ -1,10 +1,7 @@
 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,
@@ -12,10 +9,6 @@ module GeminiCache
       )
     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
@@ -25,9 +18,6 @@ module GeminiCache
       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
@@ -36,11 +26,6 @@ module GeminiCache
       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
@@ -50,10 +35,6 @@ module GeminiCache
       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
@@ -64,16 +45,10 @@ module GeminiCache
 
     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
       
@@ -83,4 +58,4 @@ module GeminiCache
       raise ApiError, "Network error: #{e.message}"
     end
   end
-end 
+end

data/lib/gemini_cache/configuration.rb

@@ -1,13 +1,7 @@
 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'
@@ -16,20 +10,12 @@ module GeminiCache
   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 
+end

data/lib/gemini_cache/item_extender.rb

@@ -5,24 +5,12 @@ module ItemExtender
   DEFAULT_TIMEOUT = 300 # seconds
   ACCURATE_MODE_CONFIG = { temperature: 0, topP: 0, topK: 1 }.freeze
 
-  # Deletes the cached item
-  # @return [void]
-  def delete
-    GeminiCache.delete(name: self['name'])
-  end
+  def delete = GeminiCache.delete(name: self['name'])
 
-  # 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)
     response = api_client.post(generate_content_endpoint) do |req|
       req.params['key'] = ENV.fetch('GEMINI_API_KEY')
@@ -33,11 +21,7 @@ module ItemExtender
   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
     

data/lib/gemini_cache.rb

@@ -8,56 +8,26 @@ 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
-  # Custom error class for GeminiCache-specific errors
   class Error < StandardError; end
 
   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 parse_html(url:, default_remover: true)
+      doc = Nokogiri::HTML(URI.open(url, "User-Agent" => "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36"))
+      %w[script style].each { |element| doc.css(element).each(&:remove) } if default_remover
+      doc
+    end
+
     def read_local_file(path:, mime_type:)
       { inline_data: { mime_type:, data: Base64.strict_encode64(File.read(path)) } }
     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
 
-    # 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 read_webpage_text(url:, default_remover: true) = { text: parse_html(url:, default_remover:).inner_text }
 
-    # 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:)
       
@@ -81,44 +51,18 @@ module GeminiCache
       find_by_name(name: response['name'])
     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
-
-    # 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
-
-    # 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_text(text:, **options) = create(parts: [{ text: }], **options)
+    def create_from_webpage(url:, **options) = create_from_text(text: read_webpage_text(url:)[:text], **options)
     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
 
-    # 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
 
-    # 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?
@@ -126,41 +70,17 @@ module GeminiCache
       response['cachedContents'].map { |item| item.extend(ItemExtender) }
     end
 
-    # 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
-
-    # 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
+    def find_by_name(name:) = list.find { |item| item['name'].eql?(name) }
+    def find_by_display_name(display_name:) = list.find { |item| item['displayName'].eql?(display_name) }
 
-    # 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 update(name:, content:) = api_client.update_cache(name, content)
 
-    # 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
 
-    # Deletes all caches
-    # @return [void]
-    def delete_all
-      list.each { |item| item.delete }
-    end
+    def delete_all() = list.each { |item| item.delete }
     alias clear delete_all
 
     private

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: gemini_cache
 version: !ruby/object:Gem::Version
-  version: 0.0.11
+  version: 0.0.12
 platform: ruby
 authors:
 - Gedean Dias
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-11-26 00:00:00.000000000 Z
+date: 2025-01-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -67,7 +66,6 @@ homepage: https://github.com/gedean/gemini_cache
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -82,8 +80,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.23
-signing_key: 
+rubygems_version: 3.6.2
 specification_version: 4
 summary: Ruby Gemini Context Caching
 test_files: []