gemini_cache 0.0.9 → 0.0.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ae4847ce3abf808c2779601462af28a47989301593355a8a39977a5df495f322
-  data.tar.gz: 71e72d0e2750d6b530d407f97a7490c65b6acbf342ad10803916b4b24d418b71
+  metadata.gz: c7e9a54d31ede523084b82ed3d94912bcbbd33ac2f0452bbc0a87d22ddc3d749
+  data.tar.gz: 7ca621fad09fc18f1a87938d2a42b289841ed7c9a6eaadd290869af4cd132613
 SHA512:
-  metadata.gz: 8ab29a93e9555626f6d1eecb189351b5d62b28805e0e90e0ba9c29cb9e5bcf8698f72dadb0621ffbf196503d186a2c341b45c387bc25f940d055bb110455ff78
-  data.tar.gz: 50a917b60662ecd5bc1cef90c0a633febfcfbe294c297525d397f60863dfaa29977e43c0743c9f717452fa7d45ce5fe2da8f11f3816d0f65fa5e06f6632675ff
+  metadata.gz: 7281d91213fa3b6243e6013e352653b89e15c0be1545ad62c11c97f3259f7afcdb673ffd82d9130c3fd61087ef555844ebe35f684c5ebb0ccd1e9fa0a9a65f7f
+  data.tar.gz: 9648a180a9c48e3ddddc52d3006603b9a8b8f418712474311c578660d8c329ceb4ca5ee23f89ab6262eb4058818e2289910dc58979702662852d50aa3ed2a85f

data/README.md

@@ -0,0 +1,153 @@
+# GeminiCache Module Usage Documentation
+
+## 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.
+
+## Requirements
+To use the module, ensure the following Ruby libraries are installed:
+
+- `faraday`
+- `open-uri`
+- `nokogiri`
+- `json`
+- `base64`
+
+## Code Structure
+
+The module includes the following components:
+
+1. **Classes and Modules**:
+   - `GeminiCache::Error`: Class for handling custom errors.
+   - `GeminiCache`: Contains the main methods for cache management and file processing.
+
+2. **Dependencies**:
+   - `gemini_cache/configuration`
+   - `gemini_cache/api_client`
+   - `gemini_cache/item_extender`
+
+## Features
+
+### 1. HTML Parsing
+Allows processing and cleaning the content of a web page.
+
+#### Syntax
+```ruby
+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.
+
+### 2. File Reading
+
+#### a) Local Files
+Reads a local file and returns its Base64 encoded data.
+```ruby
+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.
+
+#### b) Remote Files
+Reads a remote file and returns its Base64 encoded data.
+```ruby
+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.
+
+### 3. Webpage Text Reading
+Extracts text content from a web page, removing unnecessary elements.
+```ruby
+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.
+
+### 4. Cache Creation
+Creates a new cache from different data sources.
+
+#### General Syntax
+```ruby
+GeminiCache.create(parts:, display_name:, on_conflict: :raise_error, model: nil, ttl: nil)
+```
+- **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
+GeminiCache.list
+```
+- **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
+GeminiCache.update(name:, content:)
+```
+- **Parameters**:
+  - `name`: Name of the cache.
+  - `content`: Updated content.
+
+#### Cache Deletion
+- By Name:
+  ```ruby
+  GeminiCache.delete(name:)
+  ```
+- All Caches:
+  ```ruby
+  GeminiCache.delete_all
+  ```
+
+## Configuration
+The methods use configurations defined in the `gemini_cache/configuration` module, and communication is handled via `gemini_cache/api_client`.
+
+## Errors
+In case of conflicts or API errors, the module raises a custom exception `GeminiCache::Error`.
+
+## 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.
+

data/lib/gemini_cache/api_client.rb

@@ -0,0 +1,61 @@
+module GeminiCache
+  class ApiClient
+    class ApiError < StandardError; end
+
+    def initialize
+      @conn = Faraday.new(
+        url: GeminiCache.configuration.api_base_url,
+        headers: { 'Content-Type' => 'application/json' }
+      )
+    end
+
+    def create_cache(content)
+      response = @conn.post('/v1beta/cachedContents') do |req|
+        req.params['key'] = api_key
+        req.body = content
+      end
+
+      handle_response(response)
+    end
+
+    def list_caches
+      response = @conn.get('/v1beta/cachedContents') do |req|
+        req.params['key'] = api_key
+      end
+
+      handle_response(response)
+    end
+
+    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
+
+    def delete_cache(name)
+      response = @conn.delete("/v1beta/#{name}") do |req|
+        req.params['key'] = api_key
+      end
+
+      handle_response(response)
+    end
+
+    private
+
+    def api_key
+      GeminiCache.configuration.api_key || ENV.fetch('GEMINI_API_KEY')
+    end
+
+    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,21 @@
+module GeminiCache
+  class Configuration
+    attr_accessor :api_key, :api_base_url, :default_model, :default_ttl
+
+    def initialize
+      @api_base_url = 'https://generativelanguage.googleapis.com'
+      @default_model = 'gemini-1.5-flash-8b'
+      @default_ttl = 300
+    end
+  end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+  end
+end

data/lib/gemini_cache/item_extender.rb

@@ -1,46 +1,73 @@
+# frozen_string_literal: true
+
 module ItemExtender
+  GEMINI_API_BASE_URL = 'https://generativelanguage.googleapis.com'
+  DEFAULT_TIMEOUT = 300 # seconds
+  ACCURATE_MODE_CONFIG = { temperature: 0, topP: 0, topK: 1 }.freeze
+
   def delete = GeminiCache.delete(name: self['name'])
 
   def ttl=(new_ttl)
-    GeminiCache.update(name: self['name'], content: { ttl: "#{new_ttl}s" })
-    GeminiCache.get_by_name(name: self['name'])
+    GeminiCache.update(name: self['name'], content: { ttl: "#{new_ttl}s" }.to_json)
   end
-
+    
   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
+
+  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,89 @@ require 'nokogiri'
 require 'json'
 require 'base64'
 
+require 'gemini_cache/configuration'
+require 'gemini_cache/api_client'
 require 'gemini_cache/item_extender'
 
 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
+  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
+    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
-  
-    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
 
-  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
-
-  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
+    def read_local_file(path:, mime_type:)
+      { inline_data: { mime_type:, data: Base64.strict_encode64(File.read(path)) } }
+    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
+    def read_remote_file(url:, mime_type:)
+      { inline_data: { mime_type:, data: Base64.strict_encode64(URI.open(url).read) } }
+    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 }
+    def read_webpage_text(url:, default_remover: true) = { text: parse_html(url:, default_remover:).inner_text }
+
+    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.list
-    conn = Faraday.new(
-      url: 'https://generativelanguage.googleapis.com',
-      headers: { 'Content-Type' => 'application/json' }
-    )
+    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
 
-    response = conn.get("/v1beta/cachedContents") do |req|
-      req.params['key'] = ENV.fetch('GEMINI_API_KEY')
+    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) }
+    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 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) }
 
-  def self.delete(name:)
-    conn = Faraday.new(
-      url: 'https://generativelanguage.googleapis.com',
-      headers: { 'Content-Type' => 'application/json' }
-    )
+    def update(name:, content:) = api_client.update_cache(name, content)
 
-    response = conn.delete("/v1beta/#{name}") do |req|
-      req.params['key'] = ENV.fetch('GEMINI_API_KEY')
+    def delete(name:)
+      api_client.delete_cache(name)
+      true
     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
+    def delete_all() = list.each { |item| item.delete }
+    alias clear delete_all
 
-  def self.delete_all
-    GeminiCache.list.each { |item| item.delete }
-  end
+    private
 
-  class << self
-    alias clear delete_all
+    def api_client
+      @api_client ||= ApiClient.new
+    end
   end
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: gemini_cache
 version: !ruby/object:Gem::Version
-  version: 0.0.9
+  version: 0.0.12
 platform: ruby
 authors:
 - Gedean Dias
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-11-23 00:00:00.000000000 Z
+date: 2025-01-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -58,13 +57,15 @@ 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:
 - MIT
 metadata: {}
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -79,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: []