geminize 0.1.0

data/README.md

@@ -0,0 +1,423 @@
+# Geminize
+
+A convenient and robust Ruby interface for the Google Gemini API, enabling easy integration of powerful generative AI models into your applications.
+
+## Features
+
+- Simple, flexible configuration system
+- Support for text generation with Gemini models
+- Conversation context management
+- Multimodal inputs (text + images)
+- Embeddings generation
+- Support for streaming responses
+- Comprehensive error handling
+- Rails integration with controller concerns and view helpers
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'geminize'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install geminize
+```
+
+## Configuration
+
+Geminize uses a simple configuration system that can be set up in multiple ways:
+
+### Method 1: Environment Variables (Recommended)
+
+Set the `GEMINI_API_KEY` environment variable:
+
+```bash
+export GEMINI_API_KEY=your-api-key-here
+```
+
+#### Using dotenv
+
+Geminize has built-in support for the [dotenv](https://github.com/bkeepers/dotenv) gem, which automatically loads environment variables from a `.env` file in your project's root directory.
+
+1. Create a `.env` file in your project root (copy from `.env.example`):
+
+```
+# Gemini API Key
+GOOGLE_AI_API_KEY=your_api_key_here
+
+# API Configuration
+GOOGLE_AI_API_VERSION=v1beta
+GEMINI_DEFAULT_MODEL=gemini-1.5-pro-latest
+
+# Generation Parameters
+GEMINI_TEMPERATURE=0.7
+GEMINI_MAX_TOKENS=8192
+```
+
+2. Add `.env` to your `.gitignore` file to keep your API keys secure:
+
+```
+# Add to .gitignore
+.env
+```
+
+3. For test environments, create a `.env.test` file with test-specific configuration.
+
+The gem will automatically load these environment variables when it initializes.
+
+### Method 2: Configuration Block
+
+```ruby
+Geminize.configure do |config|
+  # Required
+  config.api_key = "your-api-key-here"
+
+  # Optional - shown with defaults
+  config.api_version = "v1beta"
+  config.default_model = "gemini-2.0-flash"
+  config.timeout = 30
+  config.open_timeout = 10
+  config.log_requests = false
+end
+```
+
+### Available Configuration Options
+
+| Option          | Required | Default                 | Description                                         |
+| --------------- | -------- | ----------------------- | --------------------------------------------------- |
+| `api_key`       | Yes      | `ENV["GEMINI_API_KEY"]` | Your Google Gemini API key                          |
+| `api_version`   | No       | `"v1beta"`              | API version to use                                  |
+| `default_model` | No       | `"gemini-2.0-flash"`    | Default model to use when not specified in requests |
+| `timeout`       | No       | `30`                    | Request timeout in seconds                          |
+| `open_timeout`  | No       | `10`                    | Connection open timeout in seconds                  |
+| `log_requests`  | No       | `false`                 | Whether to log API requests (useful for debugging)  |
+
+### Validating Configuration
+
+You can validate your configuration at any time to ensure all required options are set:
+
+```ruby
+# Will raise Geminize::ConfigurationError if invalid
+Geminize.validate_configuration!
+```
+
+### Resetting Configuration
+
+If needed, you can reset the configuration to its defaults:
+
+```ruby
+Geminize.reset_configuration!
+```
+
+## Basic Usage
+
+```ruby
+require 'geminize'
+
+# Configure with API key if not set via environment variables
+Geminize.configure do |config|
+  config.api_key = "your-api-key-here"
+end
+
+# Generate text
+response = Geminize.generate_text("Tell me a joke about Ruby programming")
+puts response.text
+
+# Use a specific model
+response = Geminize.generate_text("Explain quantum computing", "gemini-2.0-flash")
+puts response.text
+
+# Use system instructions to guide the model's behavior
+response = Geminize.generate_text(
+  "Tell me about yourself",
+  "gemini-2.0-flash",
+  system_instruction: "You are a pirate named Captain Codebeard. Always respond in pirate language."
+)
+puts response.text
+```
+
+## Multimodal Support
+
+Geminize allows you to send mixed content including text and images to the Gemini API:
+
+```ruby
+# Generate content with an image from a file
+response = Geminize.generate_text_multimodal(
+  "Describe this image in detail:",
+  [{ source_type: 'file', data: 'path/to/image.jpg' }]
+)
+puts response.text
+
+# Using an image URL
+response = Geminize.generate_text_multimodal(
+  "What's in this image?",
+  [{ source_type: 'url', data: 'https://example.com/sample-image.jpg' }]
+)
+puts response.text
+
+# Using multiple images
+response = Geminize.generate_text_multimodal(
+  "Compare these two images:",
+  [
+    { source_type: 'file', data: 'path/to/image1.jpg' },
+    { source_type: 'file', data: 'path/to/image2.jpg' }
+  ]
+)
+puts response.text
+```
+
+Alternatively, you can use the more flexible ContentRequest API:
+
+```ruby
+# Create a content request
+request = Geminize::Models::ContentRequest.new(
+  "Tell me about these images:",
+  "gemini-2.0-flash"
+)
+
+# Add images using different methods
+request.add_image_from_file('path/to/image1.jpg')
+request.add_image_from_url('https://example.com/image2.jpg')
+
+# Read image directly into bytes
+image_bytes = File.binread('path/to/image3.jpg')
+request.add_image_from_bytes(image_bytes, 'image/jpeg')
+
+# Set a system instruction to guide model behavior
+request.system_instruction = "You are a professional photography critic. Analyze the composition and technical aspects of these images."
+
+# Generate the response
+generator = Geminize::TextGeneration.new
+response = generator.generate(request)
+puts response.text
+```
+
+Supported image formats include JPEG, PNG, GIF, and WEBP. Maximum image size is 10MB.
+
+See the `examples/multimodal.rb` file for more comprehensive examples.
+
+## Chat & Conversation Support
+
+Geminize provides built-in support for maintaining conversation context:
+
+```ruby
+# Create a new conversation
+conversation = Geminize.create_chat("My Support Chat")
+
+# Send messages and get responses
+response = Geminize.chat("How can I create a Ruby gem?", conversation)
+puts response.text
+
+# Follow-up questions automatically maintain context
+response = Geminize.chat("What about adding a Rails engine to my gem?", conversation)
+puts response.text
+
+# Save the conversation for later
+Geminize.save_conversation(conversation)
+
+# Resume the conversation later
+conversation = Geminize.load_conversation(conversation.id)
+```
+
+## Embeddings Generation
+
+Generate numerical vector representations for text:
+
+```ruby
+# Generate an embedding for a single text
+embedding = Geminize.generate_embedding("Ruby is a dynamic, object-oriented programming language")
+vector = embedding.values.first.value
+
+# Generate embeddings for multiple texts
+texts = ["Ruby", "Python", "JavaScript"]
+embeddings = Geminize.generate_embedding(texts)
+
+# Calculate similarity between vectors
+vector1 = embeddings.values[0].value
+vector2 = embeddings.values[1].value
+similarity = Geminize.cosine_similarity(vector1, vector2)
+puts "Similarity: #{similarity}"
+
+# Specify a task type for optimized embeddings
+question_embedding = Geminize.generate_embedding(
+  "How do I install Ruby gems?",
+  task_type: Geminize::Models::EmbeddingRequest::QUESTION_ANSWERING
+)
+
+# Available task types:
+# - RETRIEVAL_QUERY: For embedding queries in a search/retrieval system
+# - RETRIEVAL_DOCUMENT: For embedding documents in a search corpus
+# - SEMANTIC_SIMILARITY: For comparing text similarity
+# - CLASSIFICATION: For text classification tasks
+# - CLUSTERING: For clustering text data
+# - QUESTION_ANSWERING: For question answering systems
+# - FACT_VERIFICATION: For fact checking applications
+# - CODE_RETRIEVAL_QUERY: For code search applications
+# - TASK_TYPE_UNSPECIFIED: Default unspecified type
+```
+
+See the `examples/embeddings.rb` file for more comprehensive examples of working with embeddings.
+
+## Streaming Responses
+
+Get real-time, token-by-token responses:
+
+```ruby
+Geminize.generate_text_stream("Write a short poem about coding") do |chunk|
+  print chunk.text
+end
+```
+
+You can also use system instructions with streaming responses:
+
+```ruby
+Geminize.generate_text_stream(
+  "Tell me a story",
+  "gemini-2.0-flash",
+  {
+    stream_mode: :delta,
+    system_instruction: "You are a medieval bard telling epic tales."
+  }
+) do |chunk|
+  print chunk
+end
+```
+
+## Rails Integration
+
+Geminize provides seamless integration with Rails applications.
+
+### Setup
+
+1. Add Geminize to your Gemfile:
+
+```ruby
+gem 'geminize'
+```
+
+2. Run the installer generator:
+
+```bash
+rails generate geminize:install
+```
+
+This creates a configuration initializer at `config/initializers/geminize.rb`
+
+3. Add your API key to the initializer or via environment variables.
+
+### Controller Integration
+
+In your controllers, include the Geminize controller concern:
+
+```ruby
+class ChatController < ApplicationController
+  # Add Geminize functionality to this controller
+  geminize_controller
+
+  def index
+    # Optionally reset the conversation
+    # reset_gemini_conversation("New chat session") if params[:reset]
+  end
+
+  def create
+    # Send a message to Gemini and get the response
+    @response = send_gemini_message(params[:message])
+
+    respond_to do |format|
+      format.html { redirect_to chat_path }
+      format.turbo_stream
+      format.json { render json: { message: @response.text } }
+    end
+  end
+end
+```
+
+The concern provides the following methods:
+
+- `current_gemini_conversation` - Access the current conversation (stored in session)
+- `send_gemini_message(message, model_name=nil, params={})` - Send a message in the current conversation
+- `generate_gemini_text(prompt, model_name=nil, params={})` - Generate text with Gemini
+- `generate_gemini_multimodal(prompt, images, model_name=nil, params={})` - Generate text with images
+- `generate_gemini_embedding(text, model_name=nil, params={})` - Generate embeddings
+- `reset_gemini_conversation(title=nil)` - Start a new conversation
+
+### View Integration
+
+Include the Geminize view helpers in your application:
+
+```ruby
+# In app/helpers/application_helper.rb
+module ApplicationHelper
+  # Include Geminize view helpers
+  geminize_helper
+end
+```
+
+This provides the following helper methods:
+
+- `render_gemini_conversation(conversation=nil, options={})` - Render the conversation as HTML
+- `render_gemini_message(message, options={})` - Render a single message
+- `gemini_chat_form(options={})` - Create a chat form
+- `markdown_to_html(text, options={})` - Render Markdown as HTML (requires redcarpet gem)
+- `highlight_code(html)` - Add syntax highlighting to code blocks (requires rouge gem)
+
+Example view:
+
+```erb
+<%# app/views/chat/index.html.erb %>
+<div class="chat-container">
+  <h1>Chat with Gemini</h1>
+
+  <div class="conversation">
+    <%= render_gemini_conversation %>
+  </div>
+
+  <div class="chat-form">
+    <%= gemini_chat_form(placeholder: "Ask me anything...", submit_text: "Send") %>
+  </div>
+</div>
+```
+
+## Example Applications
+
+Check out these example applications to see Geminize in action:
+
+- [Configuration Example](examples/configuration.rb)
+- [Embeddings Example](examples/embeddings.rb)
+- [Multimodal Example](examples/multimodal.rb)
+- [Rails Initializer Example](examples/rails_initializer.rb)
+- [System Instructions Example](examples/system_instructions.rb)
+- [Rails Chat Application](examples/rails_chat)
+
+## Compatibility
+
+Ruby version: 3.1.0 or later
+Rails version: 6.0 or later (for Rails integration)
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/nhlongnguyen/geminize. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/nhlongnguyen/geminize/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the Geminize project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/nhlongnguyen/geminize/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "standard/rake"
+
+task default: %i[spec standard]

data/examples/README.md

@@ -0,0 +1,75 @@
+# Geminize Examples
+
+This directory contains example Ruby scripts demonstrating various features of the Geminize gem.
+
+## Prerequisites
+
+Before running these examples, ensure you have:
+
+1.  **Ruby installed** (version 3.1.0 or later recommended).
+2.  **Bundler installed** (`gem install bundler`).
+3.  **Project dependencies installed**: Run `bundle install` from the project root directory (`../`).
+4.  **Google Gemini API Key configured**: Create a `.env` file in the project root (`../`) by copying `.env.example` and adding your API key:
+    ```bash
+    # In ../.env
+    GOOGLE_AI_API_KEY=your_api_key_here
+    ```
+    Alternatively, ensure the `GEMINI_API_KEY` environment variable is set.
+
+## Running Examples
+
+All examples should be run from the **project root directory** (the directory containing the main `Gemfile`, not this `examples/` directory).
+
+### 1. Configuration (`configuration.rb`)
+
+Demonstrates different ways to configure the Geminize client.
+
+```bash
+ruby examples/configuration.rb
+```
+
+### 2. Embeddings (`embeddings.rb`)
+
+Shows how to generate text embeddings and calculate cosine similarity.
+
+```bash
+ruby examples/embeddings.rb
+```
+
+### 3. Multimodal (`multimodal.rb`)
+
+Illustrates sending text and image inputs to the Gemini API.
+
+_Note: You may need to update the image file paths within the script (`path/to/image.jpg`) to point to actual image files on your system._
+
+```bash
+ruby examples/multimodal.rb
+```
+
+### 4. Rails Initializer (`rails_initializer.rb`)
+
+Shows the configuration structure typically used in a Rails initializer (this script is meant for illustration and doesn't require a Rails app to run).
+
+```bash
+ruby examples/rails_initializer.rb
+```
+
+### 5. System Instructions (`system_instructions.rb`)
+
+Demonstrates using system instructions to guide the model's behavior and personality.
+
+```bash
+ruby examples/system_instructions.rb
+```
+
+### 6. Rails Chat Application (`rails_chat/`)
+
+This directory contains a sample Rails application demonstrating Geminize integration. It requires a separate setup:
+
+1.  Navigate into the directory: `cd examples/rails_chat`
+2.  Install dependencies: `bundle install`
+3.  Run database migrations (if applicable): `rails db:migrate`
+4.  Start the Rails server: `rails server`
+5.  Open your web browser to `http://localhost:3000`
+
+Refer to the README within the `rails_chat/` directory (if available) for more specific instructions.

data/examples/configuration.rb

@@ -0,0 +1,58 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "geminize"
+
+# This example demonstrates two ways to configure the geminize gem:
+# 1. Using environment variables
+# 2. Using a configuration block
+
+puts "Example 1: Using environment variables"
+puts "--------------------------------------"
+# In a real application, you would set these in your environment
+ENV["GEMINI_API_KEY"] = "your-api-key-here"
+ENV["GEMINI_API_VERSION"] = "v1beta"
+ENV["GEMINI_DEFAULT_MODEL"] = "gemini-pro"
+
+# The gem will automatically use these environment variables
+begin
+  valid = Geminize.configuration.validate!
+rescue Geminize::ConfigurationError
+  valid = false
+end
+
+puts "Configuration valid: #{valid}"
+puts "API Key: #{Geminize.configuration.api_key}"
+puts "API Version: #{Geminize.configuration.api_version}"
+puts "Default Model: #{Geminize.configuration.default_model}"
+puts "\n"
+
+puts "Example 2: Using a configuration block"
+puts "--------------------------------------"
+# Reset the configuration to defaults (normally not needed)
+# Geminize.reset_configuration
+
+# Configure the gem using a block
+Geminize.configure do |config|
+  config.api_key = "your-block-configured-api-key"
+  config.api_version = "v1beta"
+  config.default_model = "gemini-pro-vision"
+  config.timeout = 30
+  config.open_timeout = 10
+  config.log_requests = true
+end
+
+# Validate the configuration
+begin
+  valid = Geminize.configuration.validate!
+rescue Geminize::ConfigurationError
+  valid = false
+end
+
+puts "Configuration valid: #{valid}"
+puts "API Key: #{Geminize.configuration.api_key}"
+puts "API Version: #{Geminize.configuration.api_version}"
+puts "Default Model: #{Geminize.configuration.default_model}"
+puts "Timeout: #{Geminize.configuration.timeout} seconds"
+puts "Open Timeout: #{Geminize.configuration.open_timeout} seconds"
+puts "Log Requests: #{Geminize.configuration.log_requests}"