geminize 0.1.0

data/examples/embeddings.rb

@@ -0,0 +1,195 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "geminize"
+
+# This example demonstrates how to use the Geminize embedding API
+# to generate vector embeddings for text
+
+# Configure with your API key
+Geminize.configure do |config|
+  # Use environment variable or set directly
+  config.api_key = ENV["GEMINI_API_KEY"] || "your-api-key-here"
+
+  # Optional: Set a default embedding model
+  config.default_embedding_model = "text-embedding-004"
+end
+
+puts "============================================================"
+puts "Example 1: Generate embedding for a single text"
+puts "============================================================"
+
+begin
+  # Generate embedding for a single text
+  text = "What is the meaning of life?"
+  response = Geminize.generate_embedding(text)
+
+  puts "Generated embedding with #{response.embedding_size} dimensions"
+  puts "First 5 values: #{response.embedding.take(5).inspect}"
+  puts "Total tokens: #{response.total_tokens}"
+rescue => e
+  puts "Error: #{e.message}"
+end
+
+puts "\n============================================================"
+puts "Example 2: Generate embeddings for multiple texts"
+puts "============================================================"
+
+begin
+  # Generate embeddings for multiple texts in a single API call
+  texts = [
+    "What is the meaning of life?",
+    "How much wood would a woodchuck chuck?",
+    "How does the brain work?"
+  ]
+
+  response = Geminize.generate_embedding(texts)
+
+  puts "Generated #{response.batch_size} embeddings, each with #{response.embedding_size} dimensions"
+
+  # Access individual embeddings
+  texts.each_with_index do |text, i|
+    puts "\nText: \"#{text}\""
+    puts "First 5 values: #{response.embedding_at(i).take(5).inspect}"
+  end
+
+  puts "\nTotal tokens: #{response.total_tokens}"
+rescue => e
+  puts "Error: #{e.message}"
+end
+
+puts "\n============================================================"
+puts "Example 3: Generate embeddings with task type and dimensions"
+puts "============================================================"
+
+begin
+  text = "This is a sample text for similarity comparison"
+
+  # Generate with specific task type for better performance
+  response = Geminize.generate_embedding(
+    text,
+    "text-embedding-004", # You can specify a model explicitly
+    task_type: "SEMANTIC_SIMILARITY", # Optimize for similarity comparisons
+    dimensions: 768 # Request specific dimensions (if supported by model)
+  )
+
+  puts "Generated embedding optimized for SEMANTIC_SIMILARITY"
+  puts "Dimensions: #{response.embedding_size}"
+  puts "First 5 values: #{response.embedding.take(5).inspect}"
+rescue => e
+  puts "Error: #{e.message}"
+end
+
+puts "\n============================================================"
+puts "Example 4: Batch processing for large arrays"
+puts "============================================================"
+
+begin
+  # Create a larger array of texts
+  many_texts = Array.new(120) { |i| "This is sample text number #{i}" }
+
+  # Generate embeddings with automatic batch processing
+  response = Geminize.generate_embedding(
+    many_texts,
+    nil, # Use default model
+    batch_size: 40 # Process in batches of 40 texts each
+  )
+
+  puts "Generated embeddings for #{response.batch_size} texts"
+  puts "First text embedding dimensions: #{response.embedding_size}"
+  puts "Total tokens processed: #{response.total_tokens}"
+rescue => e
+  puts "Error: #{e.message}"
+end
+
+puts "\n============================================================"
+puts "Example 5: Vector operations with embeddings"
+puts "============================================================"
+
+begin
+  # Generate embeddings for two related texts
+  text1 = "Artificial intelligence is changing the world"
+  text2 = "Machine learning technologies are transforming industries"
+
+  response1 = Geminize.generate_embedding(text1)
+  response2 = Geminize.generate_embedding(text2)
+
+  # Calculate cosine similarity
+  similarity = Geminize.cosine_similarity(response1.embedding, response2.embedding)
+
+  puts "Similarity between related texts: #{similarity.round(4)}"
+
+  # Compare with unrelated text
+  text3 = "The quick brown fox jumps over the lazy dog"
+  response3 = Geminize.generate_embedding(text3)
+
+  unrelated_similarity = Geminize.cosine_similarity(response1.embedding, response3.embedding)
+
+  puts "Similarity with unrelated text: #{unrelated_similarity.round(4)}"
+
+  # Calculate average embedding
+  avg_embedding = Geminize.average_vectors([response1.embedding, response2.embedding])
+  puts "Created average embedding vector with #{avg_embedding.size} dimensions"
+rescue => e
+  puts "Error: #{e.message}"
+end
+
+puts "\n============================================================"
+puts "Example 6: Using different task types for specific use cases"
+puts "============================================================"
+
+begin
+  # Sample texts for different use cases
+  question = "What is the capital of France?"
+  code_query = "how to sort an array in javascript"
+  document = "Paris is the capital and most populous city of France, with an estimated population of 2,175,601 residents."
+  fact = "The Earth revolves around the Sun."
+
+  puts "Demonstrating different task types for embeddings:"
+
+  # Question answering
+  qa_response = Geminize.generate_embedding(
+    question,
+    nil, # Use default model
+    task_type: Geminize::Models::EmbeddingRequest::QUESTION_ANSWERING
+  )
+  puts "\n1. QUESTION_ANSWERING task type:"
+  puts "   Text: \"#{question}\""
+  puts "   First 5 values: #{qa_response.embedding.take(5).inspect}"
+
+  # Code retrieval
+  code_response = Geminize.generate_embedding(
+    code_query,
+    nil, # Use default model
+    task_type: Geminize::Models::EmbeddingRequest::CODE_RETRIEVAL_QUERY
+  )
+  puts "\n2. CODE_RETRIEVAL_QUERY task type:"
+  puts "   Text: \"#{code_query}\""
+  puts "   First 5 values: #{code_response.embedding.take(5).inspect}"
+
+  # Document retrieval
+  document_response = Geminize.generate_embedding(
+    document,
+    nil, # Use default model
+    task_type: Geminize::Models::EmbeddingRequest::RETRIEVAL_DOCUMENT,
+    title: "Paris Facts" # Titles can be used with RETRIEVAL_DOCUMENT
+  )
+  puts "\n3. RETRIEVAL_DOCUMENT task type with title:"
+  puts "   Title: \"Paris Facts\""
+  puts "   First 5 values: #{document_response.embedding.take(5).inspect}"
+
+  # Fact verification
+  fact_response = Geminize.generate_embedding(
+    fact,
+    nil, # Use default model
+    task_type: Geminize::Models::EmbeddingRequest::FACT_VERIFICATION
+  )
+  puts "\n4. FACT_VERIFICATION task type:"
+  puts "   Text: \"#{fact}\""
+  puts "   First 5 values: #{fact_response.embedding.take(5).inspect}"
+
+  puts "\nNote: Different task types optimize the embeddings for different use cases."
+  puts "Choose the appropriate task type based on your application needs."
+rescue => e
+  puts "Error: #{e.message}"
+end

data/examples/multimodal.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require "geminize"
+
+# Configure with your API key
+Geminize.configure do |config|
+  # Use environment variable or set directly
+  config.api_key = ENV["GEMINI_API_KEY"] || "your-api-key-here"
+
+  # Specify the model to use (optional)
+  config.default_model = "gemini-2.0-flash" # This model supports multimodal inputs
+end
+
+puts "============================================================"
+puts "Example 1: Basic image and text input using a file path"
+puts "============================================================"
+
+begin
+  # 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:"
+  puts response.text
+  puts "\nFinish reason: #{response.finish_reason}"
+rescue => e
+  puts "Error: #{e.message}"
+  puts "Make sure to update the image path to a real image on your system."
+end
+
+puts "\n============================================================"
+puts "Example 2: Using image URL"
+puts "============================================================"
+
+begin
+  # Generate content with an image from a URL
+  response = Geminize.generate_text_multimodal(
+    "What's in this image?",
+    [{source_type: "url", data: "https://example.com/sample-image.jpg"}],
+    nil, # Use default model
+    temperature: 0.7
+  )
+
+  puts "Response with temperature=0.7:"
+  puts response.text
+rescue => e
+  puts "Error: #{e.message}"
+  puts "Make sure to use a valid image URL."
+end
+
+puts "\n============================================================"
+puts "Example 3: Multiple images comparison"
+puts "============================================================"
+
+begin
+  # Generate content comparing multiple images
+  response = Geminize.generate_text_multimodal(
+    "Compare these two images and describe the differences:",
+    [
+      {source_type: "file", data: "path/to/image1.jpg"},
+      {source_type: "file", data: "path/to/image2.jpg"}
+    ],
+    "gemini-1.5-pro-latest", # Explicitly specify model
+    max_tokens: 500
+  )
+
+  puts "Response (max_tokens=500):"
+  puts response.text
+rescue => e
+  puts "Error: #{e.message}"
+  puts "Make sure to update the image paths to real images on your system."
+end
+
+puts "\n============================================================"
+puts "Example 4: Using raw image bytes with MIME type"
+puts "============================================================"
+
+begin
+  # Read image directly into bytes
+  image_bytes = File.binread("path/to/image.jpg")
+
+  # Generate content with raw image bytes
+  response = Geminize.generate_text_multimodal(
+    "Analyze this image:",
+    [{source_type: "bytes", data: image_bytes, mime_type: "image/jpeg"}]
+  )
+
+  puts "Response for raw bytes input:"
+  puts response.text
+rescue => e
+  puts "Error: #{e.message}"
+  puts "Make sure to update the image path to a real image on your system."
+end
+
+puts "\n============================================================"
+puts "Example 5: Using ContentRequest directly for more control"
+puts "============================================================"
+
+begin
+  # Create a generator
+  generator = Geminize::TextGeneration.new
+
+  # Create a content request
+  request = Geminize::Models::ContentRequest.new(
+    "Tell me about these images:",
+    "gemini-1.5-pro-latest",
+    temperature: 0.3,
+    max_tokens: 800
+  )
+
+  # Add multiple images using different methods
+  request.add_image_from_file("path/to/image1.jpg")
+  request.add_image_from_url("https://example.com/image2.jpg")
+
+  # Generate the response
+  response = generator.generate(request)
+
+  puts "Response using ContentRequest directly:"
+  puts response.text
+  puts "\nUsed #{response.usage.total_tokens} tokens total"
+rescue => e
+  puts "Error: #{e.message}"
+  puts "Make sure to update the paths to real images."
+end

data/examples/rails_chat/README.md

@@ -0,0 +1,69 @@
+# Rails Chat Example
+
+This is a basic example of how to implement a chat application with the Geminize gem in a Rails application.
+
+## Features
+
+- Chat interface with Google's Gemini AI
+- Conversation memory between requests using Rails session
+- Support for Turbo and JSON responses
+- Reset conversation functionality
+
+## Implementation
+
+This example demonstrates:
+
+1. How to include Geminize controller concerns
+2. How to use Geminize view helpers
+3. How to maintain conversation state in a Rails application
+
+## File Structure
+
+- `app/controllers/chat_controller.rb` - Controller with Geminize integration
+- `app/views/chat/index.html.erb` - Chat interface view
+- `config/routes.rb` - Routes configuration
+
+## Setup in Your Application
+
+1. Add Geminize to your Gemfile:
+
+```ruby
+gem 'geminize'
+```
+
+2. Run the installer:
+
+```bash
+rails generate geminize:install
+```
+
+3. Configure your API key in `config/initializers/geminize.rb`
+
+4. Include the Geminize helpers in your `ApplicationHelper`
+
+```ruby
+module ApplicationHelper
+  geminize_helper
+end
+```
+
+5. Create your controller with Geminize support
+
+```ruby
+class YourChatController < ApplicationController
+  geminize_controller
+
+  # ... your controller actions
+end
+```
+
+6. Use the helper methods in your views
+
+```erb
+<%= render_gemini_conversation %>
+<%= gemini_chat_form %>
+```
+
+## Styling
+
+This example includes basic CSS to style the chat interface. Feel free to customize it to match your application's design.

data/examples/rails_chat/app/controllers/chat_controller.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+class ChatController < ApplicationController
+  # Include Geminize controller functionality
+  geminize_controller
+
+  def index
+    # Reset conversation if requested
+    reset_gemini_conversation("Chat with Gemini") if params[:reset]
+  end
+
+  def create
+    @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
+
+  def reset
+    reset_gemini_conversation("New Chat Session")
+    redirect_to chat_path, notice: "Started a new conversation"
+  end
+end

data/examples/rails_chat/app/views/chat/index.html.erb

@@ -0,0 +1,112 @@
+<%# Chat index view %>
+<div class="chat-container">
+  <div class="chat-header">
+    <h1>Chat with Gemini</h1>
+    <%= link_to "Start New Chat", reset_chat_path, class: "new-chat-button", data: { turbo_method: :post } %>
+  </div>
+
+  <div class="conversation-container">
+    <div class="conversation">
+      <%= render_gemini_conversation(nil, include_timestamps: true) %>
+    </div>
+  </div>
+
+  <div class="chat-form-container">
+    <%= gemini_chat_form(
+      placeholder: "Ask me anything...",
+      submit_text: "Send",
+      form_class: "chat-form",
+      input_class: "chat-input",
+      submit_class: "chat-submit"
+    ) %>
+  </div>
+</div>
+
+<% content_for :styles do %>
+<style>
+  .chat-container {
+    max-width: 800px;
+    margin: 0 auto;
+    padding: 20px;
+    font-family: system-ui, -apple-system, sans-serif;
+  }
+
+  .chat-header {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    margin-bottom: 20px;
+  }
+
+  .new-chat-button {
+    background: #6200ee;
+    color: white;
+    padding: 8px 16px;
+    border-radius: 4px;
+    text-decoration: none;
+  }
+
+  .conversation-container {
+    height: 400px;
+    overflow-y: auto;
+    border: 1px solid #e0e0e0;
+    border-radius: 8px;
+    margin-bottom: 20px;
+    padding: 16px;
+    background: #f8f9fa;
+  }
+
+  .gemini-message {
+    margin-bottom: 16px;
+    padding: 12px;
+    border-radius: 8px;
+  }
+
+  .gemini-user-message {
+    background: #e3f2fd;
+    margin-left: 20px;
+  }
+
+  .gemini-ai-message {
+    background: #f1f3f4;
+    margin-right: 20px;
+  }
+
+  .gemini-message-role {
+    font-weight: bold;
+    margin-bottom: 8px;
+  }
+
+  .gemini-message-timestamp {
+    font-size: 0.8em;
+    color: #666;
+    margin-top: 8px;
+    text-align: right;
+  }
+
+  .chat-form {
+    display: flex;
+    gap: 8px;
+  }
+
+  .chat-input {
+    flex: 1;
+    padding: 12px;
+    border: 1px solid #e0e0e0;
+    border-radius: 4px;
+    font-family: inherit;
+    resize: none;
+    height: 80px;
+  }
+
+  .chat-submit {
+    background: #6200ee;
+    color: white;
+    border: none;
+    padding: 12px 24px;
+    border-radius: 4px;
+    cursor: pointer;
+    align-self: flex-end;
+  }
+</style>
+<% end %>

data/examples/rails_chat/config/routes.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+Rails.application.routes.draw do
+  # Chat routes
+  get "chat", to: "chat#index"
+  post "chat", to: "chat#create"
+  post "chat/reset", to: "chat#reset", as: :reset_chat
+end

data/examples/rails_initializer.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# config/initializers/geminize.rb
+
+# This is an example of how to configure the Geminize gem in a Rails application.
+# Place this file in your config/initializers directory.
+
+# Configure the Geminize gem with your API key and any other settings
+Geminize.configure do |config|
+  # Required settings
+
+  # Get the API key from environment variables (recommended approach)
+  # config.api_key = ENV["GEMINI_API_KEY"]
+
+  # Or set it directly (not recommended for production)
+  config.api_key = "your-api-key-here"
+
+  # Optional settings with defaults
+
+  # API version to use
+  config.api_version = "v1beta"
+
+  # Default model to use when not specified in requests
+  config.default_model = "gemini-1.5-pro-latest"
+
+  # Request timeout in seconds
+  config.timeout = 30
+
+  # Connection open timeout in seconds
+  config.open_timeout = 10
+
+  # Enable request logging for development/debugging
+  # In production, keep this false unless debugging an issue
+  config.log_requests = Rails.env.development?
+end
+
+# Optionally validate the configuration during app initialization
+# This will raise Geminize::ConfigurationError if the configuration is invalid
+begin
+  Geminize.validate_configuration!
+  Rails.logger.info "Geminize configured successfully"
+rescue Geminize::ConfigurationError => e
+  Rails.logger.error "Geminize configuration error: #{e.message}"
+  # You might want to raise the error in development but not in production
+  raise e if Rails.env.development?
+end

data/examples/system_instructions.rb

@@ -0,0 +1,101 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "geminize"
+
+# This example demonstrates how to use system instructions with Geminize
+# System instructions allow you to guide the model's behavior and provide context
+# that influences all responses.
+
+# Configure with your API key
+Geminize.configure do |config|
+  config.api_key = ENV["GOOGLE_AI_API_KEY"] || ENV["GEMINI_API_KEY"]
+end
+
+puts "EXAMPLE 1: Basic system instruction with generate_text"
+puts "====================================================="
+
+response = Geminize.generate_text(
+  "Tell me about yourself",
+  "gemini-2.0-flash",
+  system_instruction: "You are a cat named Whiskers. Always speak like a cat."
+)
+
+puts "Response:\n#{response.text}"
+puts "\n"
+
+puts "EXAMPLE 2: Using system instructions with ContentRequest directly"
+puts "=============================================================="
+
+request = Geminize::Models::ContentRequest.new(
+  "Explain quantum computing",
+  "gemini-2.0-flash",
+  temperature: 0.7,
+  max_tokens: 150
+)
+
+request.system_instruction = "You are a science teacher speaking to a 10-year-old. Use simple language."
+
+generator = Geminize::TextGeneration.new
+response = generator.generate(request)
+
+puts "Response:\n#{response.text}"
+puts "\n"
+
+puts "EXAMPLE 3: System instructions with conversation"
+puts "=============================================="
+
+# Start a new conversation with a system instruction
+conversation = Geminize.create_chat("Role-playing Chat")
+
+# The system instruction guides the entire conversation
+conversation.set_system_instruction("You are a ship's computer named HAL on a spaceship. Respond in a calm, slightly robotic manner with space-related terminology.")
+
+# First message
+response_hash = Geminize.chat("Hello there, who are you?", conversation)
+puts "Response 1:\n#{response_hash[:response].text}\n"
+
+# Follow-up
+response_hash = Geminize.chat("What can you help me with?", conversation)
+puts "Response 2:\n#{response_hash[:response].text}\n"
+
+puts "EXAMPLE 4: Streaming with system instructions"
+puts "==========================================="
+
+puts "Response:"
+Geminize.generate_text_stream(
+  "Write a short introduction to a mystery novel",
+  "gemini-2.0-flash",
+  {
+    stream_mode: :delta,
+    max_tokens: 150,
+    system_instruction: "You are a noir detective writer from the 1940s."
+  }
+) do |chunk|
+  print chunk unless chunk.is_a?(Hash)
+end
+
+puts "\n\nEXAMPLE 5: Different personas with system instructions"
+puts "====================================================="
+
+personas = [
+  "You are a Victorian-era poet. Use flowery, elaborate language.",
+  "You are a modern tech startup founder. Use buzzwords and be enthusiastic.",
+  "You are a grumpy old professor. Be critical and reference obscure theories."
+]
+
+prompt = "What do you think about social media?"
+
+personas.each_with_index do |persona, i|
+  puts "\nPersona #{i + 1}:"
+  puts "-" * 50
+  response = Geminize.generate_text(
+    prompt,
+    "gemini-2.0-flash",
+    system_instruction: persona,
+    max_tokens: 150
+  )
+  puts response.text
+  puts "-" * 50
+end