friday_gemini_ai 0.1.3 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 66b53a7e6a9cdf4e1321c477ab5b151159f7b176907b620264bfcb81b4dc0955
-  data.tar.gz: 42dea151c596e24f2c96f40710bc4a61bc1448516182791af4bd6ce855a2f4b2
+  metadata.gz: eae8a647419cdfdc347552b710246c592d3cda16ca8bea9e73df6d3e11c6f4dd
+  data.tar.gz: 6fe311f701d533f22bf6a754f9aa1c8e8f5bdf1d46bb64c2ff9d8b6b40f2ecf9
 SHA512:
-  metadata.gz: dad93b02ef3f339ded728ce61d2ffd98af06f332347e5d57c707c94052f8799cb1776fd8ba4119ee1e52f46adca495303024c17b0ac134eedfd9a00373425415
-  data.tar.gz: dc31beb2d7af9c8aae31d81df9416ed67b1c7b243c8f258fedd36f523a6860160432e4ba6424f50098889eb29da4d4bf72891437d4de12c868fcf4969155c479
+  metadata.gz: 84f4aae3ebcb6acfce3eb659e98a99729a67c74ba8f2ac8310d18858369f946bc1eacabbc12e35630bfd858dec1ccf17b3bf1e931f061404bee6da9dcc4812a8
+  data.tar.gz: 198b0d1bcf660d3110d20f87430c8f858b9fb18612f413b71dfa4f1f2817f40a6c7e5eae6977809dc207cffebb1cd2823d4f2e49c2a54f493c7460a0df99c679

data/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Niladri Das
+Copyright (c) friday_gemini_ai
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,104 +1,133 @@
-# Friday Gemini AI Ruby Gem
-
-## Table of Contents
-1. [Installation](#installation)
-2. [Configuration](#configuration)
-3. [Usage](#usage)
-   - [Text Generation](#text-generation)
-   - [Chat](#chat)
-   - [Error Handling](#error-handling)
-4. [Logging](#logging)
-5. [Security](#security)
-6. [Testing](#testing)
-7. [Contributing](#contributing)
+# Friday Gemini AI
+
+[![Gem Version](https://badge.fury.io/rb/friday_gemini_ai.svg)](https://badge.fury.io/rb/friday_gemini_ai)
+[![CI](https://github.com/bniladridas/friday_gemini_ai/actions/workflows/ci.yml/badge.svg)](https://github.com/bniladridas/friday_gemini_ai/actions/workflows/ci.yml)
+[![Security](https://github.com/bniladridas/friday_gemini_ai/workflows/Security/badge.svg)](https://github.com/bniladridas/friday_gemini_ai/actions/workflows/security.yml)
+[![Release](https://github.com/bniladridas/friday_gemini_ai/workflows/Release/badge.svg)](https://github.com/bniladridas/friday_gemini_ai/actions/workflows/release.yml)
+
+Ruby gem for Google's Gemini AI models.
 
 ## Installation
 
-### From RubyGems
 ```bash
 gem install friday_gemini_ai
 ```
 
-### Using Bundler
-Add to your Gemfile:
-```ruby
-gem 'friday_gemini_ai'
+Create a `.env` file and add your API key:
 ```
-
-## Configuration
-
-Set your API key:
-```bash
-export GEMINI_API_KEY='your_api_key_here'
+GEMINI_API_KEY=your_api_key_here
 ```
 
 ## Usage
 
-### Text Generation
 ```ruby
-require 'gemini_ai'
+require_relative 'lib/gemini'
 
-client = GeminiAI::Client.new
-response = client.generate_text('Tell me a joke')
-puts response
-```
-
-### Chat
-```ruby
-messages = [
-  { role: 'user', content: 'Hello' },
-  { role: 'model', content: 'Hi there!' },
-  { role: 'user', content: 'How are you?' }
-]
+GeminiAI.load_env
 
-response = client.chat(messages)
+# Use the latest Gemini 2.5 Pro (default)
+client = GeminiAI::Client.new
+response = client.generate_text('Write a haiku about Ruby')
 puts response
-```
 
-### Error Handling
-```ruby
-begin
-  client.generate_text('')
-rescue GeminiAI::Error => e
-  puts "Error: #{e.message}"
-end
+# Or choose a specific model
+flash_client = GeminiAI::Client.new(model: :flash)  # Gemini 2.5 Flash
+pro_client = GeminiAI::Client.new(model: :pro)      # Gemini 2.5 Pro
 ```
 
-## Logging
-
-### Configuration
-```ruby
-# Set logging level
-GeminiAI::Client.logger.level = Logger::INFO
-
-# Log to file
-GeminiAI::Client.logger = Logger.new('logfile.log')
+```bash
+./bin/gemini test
+./bin/gemini generate "Your prompt here"
+./bin/gemini chat
 ```
 
-### Log Levels
-- DEBUG: Detailed debug information
-- INFO: General operational messages
-- WARN: Warning conditions
-- ERROR: Error conditions
-
-## Security
-
-### API Key Protection
-- Never hardcode API keys
-- Use environment variables
-- Automatic key masking in logs
+## Supported Models
+
+| Model Key | Model ID | Description |
+|-----------|----------|-------------|
+| `:pro` | `gemini-2.5-pro` | Latest and most capable model |
+| `:flash` | `gemini-2.5-flash` | Fast and efficient latest model |
+| `:flash_2_0` | `gemini-2.0-flash` | Previous generation fast model |
+| `:flash_lite` | `gemini-2.0-flash-lite` | Lightweight model |
+| `:pro_1_5` | `gemini-1.5-pro` | Gemini 1.5 Pro model |
+| `:flash_1_5` | `gemini-1.5-flash` | Gemini 1.5 Flash model |
+| `:flash_8b` | `gemini-1.5-flash-8b` | Compact 8B parameter model |
+
+**Model Selection Guide:**
+- Use `:pro` for complex reasoning and analysis
+- Use `:flash` for fast, general-purpose tasks  
+- Use `:flash_2_0` for compatibility with older workflows
+- Use `:flash_lite` for simple, lightweight tasks
+
+## What You Can Do
+
+**Text Generation**
+- Generate creative content, stories, and articles
+- Create explanations and educational content
+- Write code comments and documentation
+
+**Conversational AI**
+- Build multi-turn chat applications
+- Create interactive Q&A systems
+- Develop conversational interfaces
+
+**Image Analysis**
+- Analyze images with text prompts
+- Extract information from visual content
+- Generate descriptions of images
+
+**Quick Tasks**
+- Test ideas and prompts via CLI
+- Prototype AI-powered features
+- Generate content with custom parameters
+
+## Features
+
+- Text generation and chat conversations
+- Support for Gemini 2.5, 2.0, and 1.5 model families
+- Configurable parameters (temperature, tokens, top-p, top-k)
+- Error handling and API key security
+- CLI interface and .env integration
+
+## Documentation
+
+**Getting Started**
+- [Overview](docs/start/overview.md) - Features and capabilities
+- [Quickstart](docs/start/quickstart.md) - 5-minute setup
+
+**Reference**
+- [API Reference](docs/reference/api.md) - Method documentation
+- [Usage Guide](docs/reference/usage.md) - Examples and patterns
+- [Models](docs/reference/models.md) - Gemini 2.5 Pro, Flash, and more
+- [Capabilities](docs/reference/capabilities.md) - Text generation and chat
+- [Cookbook](docs/reference/cookbook.md) - Code recipes
+- [Versions](docs/reference/versions.md) - API compatibility
+
+**Guides**
+- [Best Practices](docs/guides/practices.md) - Security and performance
+- [Troubleshooting](docs/guides/troubleshoot.md) - Common solutions
+- [Workflows](docs/guides/workflows.md) - CI/CD and automation
+- [Resources](docs/guides/resources.md) - Migration and extras
+- [Community](docs/guides/community.md) - Contributing and support
+- [Changelog](CHANGELOG.md) - Version history and changes
+
+## Examples
+
+- `examples/basic.rb` - Text generation and chat
+- `examples/advanced.rb` - Configuration and error handling
 
 ## Testing
 
-Run the test suite:
 ```bash
-bundle exec ruby test/gemini_ai_test.rb
+ruby tests/runner.rb
+ruby tests/unit/client.rb
+ruby tests/integration/api.rb
 ```
 
 ## Contributing
 
-1. Fork the repository
-2. Create your feature branch
-3. Commit your changes
-4. Push to the branch
-5. Create a new Pull Request
+Fork, branch, commit, push, pull request.
+
+## License
+
+MIT - see [LICENSE](LICENSE)

data/lib/{gemini_ai.rb → core/client.rb}

@@ -2,22 +2,35 @@ require 'httparty'
 require 'json'
 require 'base64'
 require 'logger'
+require 'dotenv/load'
+require_relative 'errors'
 
 module GeminiAI
-  class Error < StandardError; end
-
+  # Core client class for Gemini AI API communication
   class Client
     BASE_URL = 'https://generativelanguage.googleapis.com/v1/models'
     MODELS = {
-      pro: 'gemini-2.0-flash',
-      flash: 'gemini-2.0-flash',
-      flash_lite: 'gemini-2.0-flash-lite'
+      # Gemini 2.5 models (latest)
+      pro: 'gemini-2.5-pro',
+      flash: 'gemini-2.5-flash',
+      
+      # Gemini 2.0 models
+      flash_2_0: 'gemini-2.0-flash',
+      flash_lite: 'gemini-2.0-flash-lite',
+      
+      # Legacy aliases for backward compatibility
+      pro_2_0: 'gemini-2.0-flash',
+      
+      # Gemini 1.5 models (for specific use cases)
+      pro_1_5: 'gemini-1.5-pro',
+      flash_1_5: 'gemini-1.5-flash',
+      flash_8b: 'gemini-1.5-flash-8b'
     }
 
     # Configure logging
     def self.logger
       @logger ||= Logger.new(STDOUT).tap do |log|
-        log.level = Logger::DEBUG  # Changed to DEBUG for more information
+        log.level = Logger::DEBUG
         log.formatter = proc do |severity, datetime, progname, msg|
           # Mask any potential API key in logs
           masked_msg = msg.to_s.gsub(/AIza[a-zA-Z0-9_-]{35,}/, '[REDACTED]')
@@ -30,6 +43,11 @@ module GeminiAI
       # Prioritize passed API key, then environment variable
       @api_key = api_key || ENV['GEMINI_API_KEY']
       
+      # Rate limiting - track last request time
+      @last_request_time = nil
+      # More conservative rate limiting in CI environments
+      @min_request_interval = (ENV['CI'] == 'true' || ENV['GITHUB_ACTIONS'] == 'true') ? 3.0 : 1.0
+      
       # Extensive logging for debugging
       self.class.logger.debug("Initializing Client")
       self.class.logger.debug("API Key present: #{!@api_key.nil?}")
@@ -128,7 +146,10 @@ module GeminiAI
       }
     end
 
-    def send_request(body, model: nil)
+    def send_request(body, model: nil, retry_count: 0)
+      # Rate limiting - ensure minimum interval between requests
+      rate_limit_delay
+      
       current_model = model ? MODELS.fetch(model) { MODELS[:pro] } : @model
       url = "#{BASE_URL}/#{current_model}:generateContent?key=#{@api_key}"
 
@@ -145,26 +166,37 @@ module GeminiAI
             'Content-Type' => 'application/json',
             'x-goog-api-client' => 'gemini_ai_ruby_gem/0.1.0'
           },
-          # Add timeout to prevent hanging
           timeout: 30
         )
 
         self.class.logger.debug("Response Code: #{response.code}")
         self.class.logger.debug("Response Body: #{response.body}")
 
-        parse_response(response)
+        parse_response(response, retry_count, body, model)
       rescue HTTParty::Error, Net::OpenTimeout => e
         self.class.logger.error("API request failed: #{e.message}")
         raise Error, "API request failed: #{e.message}"
       end
     end
 
-    def parse_response(response)
+    def parse_response(response, retry_count, body, model)
       case response.code
       when 200
         text = response.parsed_response
                .dig('candidates', 0, 'content', 'parts', 0, 'text')
         text || 'No response generated'
+      when 429
+        # Rate limit exceeded - implement exponential backoff
+        max_retries = 3
+        if retry_count < max_retries
+          wait_time = (2 ** retry_count) * 5 # 5, 10, 20 seconds
+          self.class.logger.warn("Rate limit hit (429). Retrying in #{wait_time}s (attempt #{retry_count + 1}/#{max_retries})")
+          sleep(wait_time)
+          return send_request(body, model: model, retry_count: retry_count + 1)
+        else
+          self.class.logger.error("Rate limit exceeded after #{max_retries} retries")
+          raise Error, "Rate limit exceeded. Please check your quota and billing details."
+        end
       else
         error_message = response.parsed_response['error']&.dig('message') || response.body
         self.class.logger.error("API Error: #{error_message}")
@@ -172,6 +204,22 @@ module GeminiAI
       end
     end
 
+    # Rate limiting to prevent hitting API limits
+    def rate_limit_delay
+      current_time = Time.now
+      
+      if @last_request_time
+        time_since_last = current_time - @last_request_time
+        if time_since_last < @min_request_interval
+          sleep_time = @min_request_interval - time_since_last
+          self.class.logger.debug("Rate limiting: sleeping #{sleep_time.round(2)}s")
+          sleep(sleep_time)
+        end
+      end
+      
+      @last_request_time = Time.now
+    end
+
     # Mask API key for logging and error reporting
     def mask_api_key(key)
       return '[REDACTED]' if key.nil?
@@ -182,4 +230,4 @@ module GeminiAI
       "#{key[0,4]}#{'*' * (key.length - 8)}#{key[-4,4]}"
     end
   end
-end
+end

data/lib/core/errors.rb

@@ -0,0 +1,19 @@
+module GeminiAI
+  # Base error class for all GeminiAI related errors
+  class Error < StandardError; end
+  
+  # API related errors
+  class APIError < Error; end
+  
+  # Authentication errors
+  class AuthenticationError < Error; end
+  
+  # Rate limit errors
+  class RateLimitError < Error; end
+  
+  # Invalid request errors
+  class InvalidRequestError < Error; end
+  
+  # Network/connection errors
+  class NetworkError < Error; end
+end

data/lib/core/version.rb

@@ -0,0 +1,3 @@
+module GeminiAI
+  VERSION = '0.1.4'
+end

data/lib/gemini.rb

@@ -0,0 +1,18 @@
+# Main entry point for the GeminiAI gem
+require_relative 'core/version'
+require_relative 'core/errors'
+require_relative 'core/client'
+require_relative 'utils/loader'
+require_relative 'utils/logger'
+
+module GeminiAI
+  # Convenience method to create a new client
+  def self.new(api_key = nil, **options)
+    Client.new(api_key, **options)
+  end
+  
+  # Load environment variables
+  def self.load_env(file_path = '.env')
+    Utils::Loader.load(file_path)
+  end
+end

data/lib/utils/loader.rb

@@ -0,0 +1,18 @@
+module GeminiAI
+  module Utils
+    # Utility class for loading environment variables from .env files
+    class Loader
+      def self.load(file_path = '.env')
+        return unless File.exist?(file_path)
+        
+        File.readlines(file_path).each do |line|
+          line = line.strip
+          next if line.empty? || line.start_with?('#')
+          
+          key, value = line.split('=', 2)
+          ENV[key] = value if key && value
+        end
+      end
+    end
+  end
+end

data/lib/utils/logger.rb

@@ -0,0 +1,35 @@
+require 'logger'
+
+module GeminiAI
+  module Utils
+    # Centralized logging utility
+    class Logger
+      def self.instance
+        @logger ||= ::Logger.new(STDOUT).tap do |log|
+          log.level = ::Logger::INFO
+          log.formatter = proc do |severity, datetime, progname, msg|
+            # Mask any potential API key in logs
+            masked_msg = msg.to_s.gsub(/AIza[a-zA-Z0-9_-]{35,}/, '[REDACTED]')
+            "#{datetime}: #{severity} -- #{masked_msg}\n"
+          end
+        end
+      end
+      
+      def self.debug(message)
+        instance.debug(message)
+      end
+      
+      def self.info(message)
+        instance.info(message)
+      end
+      
+      def self.warn(message)
+        instance.warn(message)
+      end
+      
+      def self.error(message)
+        instance.error(message)
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: friday_gemini_ai
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.5
 platform: ruby
 authors:
-- bniladridas
+- Niladri Das
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-03-03 00:00:00.000000000 Z
+date: 2025-08-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty
@@ -75,7 +75,12 @@ extra_rdoc_files: []
 files:
 - LICENSE
 - README.md
-- lib/gemini_ai.rb
+- lib/core/client.rb
+- lib/core/errors.rb
+- lib/core/version.rb
+- lib/gemini.rb
+- lib/utils/loader.rb
+- lib/utils/logger.rb
 homepage: https://github.com/bniladridas/friday_gemini_ai
 licenses:
 - MIT
@@ -95,7 +100,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
 summary: A Ruby gem for interacting with Google's Gemini AI models