geminize 0.1.1 → 1.1.0

data/.memory_bank/tasks.md

@@ -0,0 +1,98 @@
+# Tasks
+
+## Current Tasks
+
+### Documentation
+
+- [ ] Review and improve YARD documentation
+- [ ] Add more code examples
+- [ ] Update README with latest features
+- [ ] Create diagrams for architecture overview
+
+### Feature Development
+
+- [ ] Support for new Gemini models as they become available
+- [ ] Add support for function calling capabilities
+- [ ] Implement batch embedding generation
+- [ ] Improve conversation persistence with adapter pattern for multiple storage options
+- [ ] **Models API Integration**:
+  - [x] Enhance `model_info.rb` to support full model metadata
+  - [x] Update/create `Models::Model` class to match API response structure
+  - [x] Implement `Models::ModelList` class for handling paginated results
+  - [x] Add methods to `RequestBuilder` for models endpoints
+  - [x] Add client methods for models endpoints
+  - [x] Add convenience methods to main Geminize module
+  - [x] Implement helper methods for model capability filtering
+  - [x] Add comprehensive tests for models functionality
+  - [x] Update documentation with models API examples
+
+### Testing
+
+- [ ] Expand test coverage
+- [ ] Add integration tests for streaming
+- [ ] Update VCR cassettes with latest API responses
+- [ ] Add benchmarks for performance testing
+
+### Improvements
+
+- [ ] Optimize streaming buffer management
+- [ ] Enhance error messages with more context
+- [ ] Reduce memory footprint for large responses
+- [ ] Add telemetry options for tracking API usage
+
+### Bug Fixes
+
+- [ ] Fix potential memory leak in streaming implementation
+- [ ] Address timeout handling edge cases
+- [ ] Improve error handling for network failures
+- [ ] Fix MIME type detection for unusual file extensions
+
+## Completed Tasks
+
+### Core Implementation
+
+- [x] Basic client implementation
+- [x] Text generation support
+- [x] Chat conversation support
+- [x] Embeddings generation
+- [x] Streaming response handling
+- [x] Models API Integration
+
+### Documentation
+
+- [x] Initial README with examples
+- [x] YARD documentation for public methods
+- [x] Example scripts
+
+### Testing
+
+- [x] Basic test suite with RSpec
+- [x] VCR setup for API mocking
+- [x] Unit tests for core functionality
+
+### Error Handling
+
+- [x] Error class hierarchy
+- [x] API error mapping
+- [x] Input validation
+
+## Backlog
+
+### Features
+
+- [ ] Rails integration improvements
+- [ ] Async API support
+- [ ] Advanced vector operations
+- [ ] Batch processing for multiple requests
+- [ ] CLI tool for quick testing
+- [ ] Models API enhancements:
+  - [ ] Caching model information to reduce API calls
+  - [ ] Smart model selection based on input requirements
+  - [ ] Model comparison utilities
+
+### Optimizations
+
+- [ ] Reduce API call overhead
+- [ ] Implement request compression
+- [ ] Add response caching
+- [ ] Improve retry strategies

data/.memory_bank/techContext.md

@@ -0,0 +1,73 @@
+# Technical Context
+
+## Core Architecture
+
+The Geminize gem follows a modular architecture with clear separation of concerns:
+
+### Main Components
+
+- **Client**: HTTP communication with the Gemini API
+- **TextGeneration**: Text generation functionality
+- **Embeddings**: Vector representation generation
+- **Chat**: Conversation management
+- **Models**: Data structures for requests/responses
+- **Middleware**: Request processing pipeline
+- **Configuration**: Environment and runtime configuration
+
+## Key Technologies
+
+- **Ruby 3.1+**: Modern Ruby language features
+- **Faraday**: HTTP client library for API communication
+- **Faraday-Retry**: Retry mechanism for transient failures
+- **MIME-Types**: MIME type detection for multimodal content
+- **JSON**: Data serialization and parsing
+
+## Code Organization
+
+```
+lib/geminize/
+  ├── client.rb                # HTTP client implementation
+  ├── configuration.rb         # Configuration management
+  ├── text_generation.rb       # Text generation functionality
+  ├── chat.rb                  # Chat conversation handling
+  ├── embeddings.rb            # Embedding vector generation
+  ├── conversation_service.rb  # Conversation state management
+  ├── request_builder.rb       # API request construction
+  ├── vector_utils.rb          # Vector manipulation utilities
+  ├── validators.rb            # Input validation functions
+  ├── errors.rb                # Error class definitions
+  ├── error_mapper.rb          # API error mapping
+  ├── error_parser.rb          # Error response parsing
+  ├── models/                  # Data models
+  │   ├── content_request.rb   # Text generation request
+  │   ├── content_response.rb  # API response data structure
+  │   ├── embedding_request.rb # Embedding generation request
+  │   ├── embedding_response.rb # Vector embedding response
+  │   ├── conversation.rb      # Conversation state
+  │   ├── message.rb           # Chat message structure
+  │   └── ...
+  └── middleware/              # Request processing middleware
+      └── error_handler.rb     # Error handling middleware
+```
+
+## Dependencies
+
+- **Runtime Dependencies**:
+
+  - faraday (~> 2.0)
+  - faraday-retry (~> 2.0)
+  - mime-types (~> 3.5)
+
+- **Development Dependencies**:
+  - rspec (~> 3.0)
+  - standard (~> 1.3)
+  - vcr (~> 6.0)
+  - webmock (~> 3.14)
+  - dotenv (~> 2.8)
+
+## Configuration Approaches
+
+- Environment variables (GEMINI_API_KEY)
+- Dotenv integration (.env file loading)
+- Programmatic configuration via block syntax
+- Default configuration with override options

data/.tool-versions

@@ -0,0 +1 @@
+ruby 3.3.4

data/CHANGELOG.md

@@ -1,4 +1,30 @@
-## [Unreleased]
+## [1.1.0] - 2025-05-02
+
+### Added
+
+- Comprehensive Models API for discovering and filtering Gemini models
+  - Added `list_models` and `list_all_models` methods for retrieving available models
+  - Added `get_model` method for fetching specific model details
+  - Added filtering methods to find models by capability:
+    - `get_content_generation_models`
+    - `get_embedding_models`
+    - `get_chat_models`
+    - `get_streaming_models`
+  - Added `get_models_by_method` to filter by specific generation methods
+  - Extended `ModelList` class with comprehensive filtering capabilities
+  - Added model capability inspection methods
+  - Implemented pagination support for model listing
+  - Added caching for model information to reduce API calls
+  - Added comprehensive VCR tests for Models API functionality
+  - Updated documentation with Models API examples
+
+## [1.0.0] - 2025-05-02
+
+### Removed
+
+- Removed Rails-related integration from the gem, simplifying usage.
+
+## [0.1.1] - 2025-05-01
 
 ### Added
 

data/README.md

@@ -11,7 +11,7 @@ A convenient and robust Ruby interface for the Google Gemini API, enabling easy
 - Embeddings generation
 - Support for streaming responses
 - Comprehensive error handling
-- Rails integration with controller concerns and view helpers
+- Complete Models API for discovering and filtering available models
 
 ## Installation
 
@@ -57,11 +57,8 @@ 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
+GEMINI_MODEL=gemini-2.0-flash
+GEMINI_EMBEDDING_MODEL=gemini-embedding-exp-03-07
 ```
 
 2. Add `.env` to your `.gitignore` file to keep your API keys secure:
@@ -311,120 +308,59 @@ end
 puts "\n" # Add a newline after streaming
 ```
 
-## Rails Integration
+Check out these example applications to see Geminize in action:
 
-Geminize provides seamless integration with Rails applications.
+- [Configuration Example](examples/configuration.rb)
+- [Embeddings Example](examples/embeddings.rb)
+- [Multimodal Example](examples/multimodal.rb)
+- [System Instructions Example](examples/system_instructions.rb)
+- [Models API Example](examples/models_api.rb)
 
-### Setup
+## Working with Models
 
-1. Add Geminize to your Gemfile:
+Geminize provides a comprehensive API for querying and working with available Gemini models:
 
 ```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
+require 'geminize'
+# Assumes API key is set via environment variables (e.g., in .env)
 
-In your controllers, include the Geminize controller concern:
+# List available models
+models = Geminize.list_models
+puts "Available models: #{models.size}"
 
-```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
+# Get details about a specific model
+model = Geminize.get_model("gemini-1.5-pro")
+puts "Model: #{model.display_name}"
+puts "Token limits: #{model.input_token_limit} input, #{model.output_token_limit} output"
 
-  def create
-    # Send a message to Gemini and get the response
-    @response = send_gemini_message(params[:message])
+# Find models by capability
+embedding_models = Geminize.get_embedding_models
+content_models = Geminize.get_content_generation_models
+streaming_models = Geminize.get_streaming_models
 
-    respond_to do |format|
-      format.html { redirect_to chat_path }
-      format.turbo_stream
-      format.json { render json: { message: @response.text } }
-    end
-  end
+# Check if a model supports a specific capability
+if model.supports_content_generation?
+  puts "This model supports content generation"
 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
+if model.supports_embedding?
+  puts "This model supports embeddings"
 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>
+# Find models with high context windows
+high_context_models = Geminize.list_all_models.filter_by_min_input_tokens(100_000)
+puts "Models with 100k+ context: #{high_context_models.map(&:id).join(', ')}"
 ```
 
-## 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)
+For more comprehensive examples, see [examples/models_api.rb](examples/models_api.rb).
 
 ## 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.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rspec` 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`.
 

data/examples/README.md

@@ -11,10 +11,9 @@ Before running these examples, ensure you have:
 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
+    # In .env
+    GEMINI_API_KEY=your_api_key_here
     ```
-    Alternatively, ensure the `GEMINI_API_KEY` environment variable is set.
 
 ## Running Examples
 
@@ -25,7 +24,7 @@ All examples should be run from the **project root directory** (the directory co
 Demonstrates different ways to configure the Geminize client.
 
 ```bash
-ruby examples/configuration.rb
+bundle exec ruby examples/configuration.rb
 ```
 
 ### 2. Embeddings (`embeddings.rb`)
@@ -33,7 +32,7 @@ ruby examples/configuration.rb
 Shows how to generate text embeddings and calculate cosine similarity.
 
 ```bash
-ruby examples/embeddings.rb
+bundle exec ruby examples/embeddings.rb
 ```
 
 ### 3. Multimodal (`multimodal.rb`)
@@ -43,33 +42,13 @@ 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
+bundle exec 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`)
+### 4. System Instructions (`system_instructions.rb`)
 
 Demonstrates using system instructions to guide the model's behavior and personality.
 
 ```bash
-ruby examples/system_instructions.rb
+bundle exec 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/embeddings.rb

@@ -55,7 +55,6 @@ begin
 
   puts "\nGenerated #{embeddings.size} embeddings."
   puts "Total tokens (approximated by summing individual calls): #{total_tokens}"
-
 rescue => e
   puts "Error: #{e.message}"
 end
@@ -85,25 +84,24 @@ end
 puts "\n============================================================"
 puts "Example 4: Batch processing for large arrays (COMMENTED OUT)"
 puts "============================================================"
-=begin # Commenting out Example 4 due to potential model/API limitations with batching
-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
-=end
+# # Commenting out Example 4 due to potential model/API limitations with batching
+# 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 "# Example 4 skipped due to potential issues with batch embedding support."
 
 puts "\n============================================================"

data/examples/models_api.rb

@@ -0,0 +1,125 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "geminize"
+require "pp"
+
+# Configure the library with your API key
+Geminize.configure do |config|
+  # Load API key from .env file or environment variables
+  config.api_key = ENV["GEMINI_API_KEY"]
+  # Use the latest API version
+  config.api_version = "v1beta"
+end
+
+# Helper method to display model information
+def display_model(model)
+  puts "========================"
+  puts "Model: #{model.display_name} (#{model.name})"
+  puts "Base Model ID: #{model.base_model_id}"
+  puts "Version: #{model.version}"
+  puts "Description: #{model.description}"
+  puts "Input Token Limit: #{model.input_token_limit}"
+  puts "Output Token Limit: #{model.output_token_limit}"
+  puts "Temperature: #{model.temperature}"
+  puts "Max Temperature: #{model.max_temperature}"
+  puts "Top P: #{model.top_p}"
+  puts "Top K: #{model.top_k}"
+  puts "Supported Methods: #{model.supported_generation_methods.join(", ")}"
+  puts "Capabilities:"
+  puts "  - Content Generation: #{model.supports_content_generation?}"
+  puts "  - Chat: #{model.supports_message_generation?}"
+  puts "  - Embedding: #{model.supports_embedding?}"
+  puts "  - Streaming: #{model.supports_streaming?}"
+  puts "========================\n\n"
+end
+
+puts "=== MODELS API EXAMPLES ==="
+
+# Example 1: List models (first page)
+puts "\n=== Example 1: List first page of models ==="
+begin
+  model_list = Geminize.list_models(page_size: 5)
+  puts "Found #{model_list.size} models on first page"
+  puts "Has more pages: #{model_list.has_more_pages?}"
+  puts "Next page token: #{model_list.next_page_token}"
+  puts "\nFirst model details:"
+  display_model(model_list.first) if model_list.first
+rescue => e
+  puts "Error listing models: #{e.message}"
+end
+
+# Example 2: Get detailed info for a specific model
+puts "\n=== Example 2: Get specific model info ==="
+begin
+  model = Geminize.get_model("gemini-1.5-flash")
+  puts "Retrieved model details:"
+  display_model(model)
+rescue => e
+  puts "Error getting model: #{e.message}"
+end
+
+# Example 3: Get all models (handling pagination)
+puts "\n=== Example 3: Get all models (handling pagination) ==="
+begin
+  all_models = Geminize.list_all_models
+  puts "Retrieved #{all_models.size} models in total"
+rescue => e
+  puts "Error listing all models: #{e.message}"
+end
+
+# Example 4: Filter models by capability
+puts "\n=== Example 4: Filter models by capability ==="
+begin
+  # Get models that support embedding
+  embedding_models = Geminize.get_embedding_models
+  puts "Found #{embedding_models.size} models that support embeddings"
+
+  # Get models that support content generation
+  content_models = Geminize.get_content_generation_models
+  puts "Found #{content_models.size} models that support content generation"
+
+  # Get models that support chat
+  chat_models = Geminize.get_chat_models
+  puts "Found #{chat_models.size} models that support chat"
+
+  # Get models that support streaming
+  streaming_models = Geminize.get_streaming_models
+  puts "Found #{streaming_models.size} models that support streaming"
+rescue => e
+  puts "Error filtering models: #{e.message}"
+end
+
+# Example 5: Filter models by specific method
+puts "\n=== Example 5: Filter models by specific method ==="
+begin
+  method_models = Geminize.get_models_by_method("generateContent")
+  puts "Found #{method_models.size} models that support generateContent"
+
+  # Display a specific model from the filtered list
+  if method_models.size > 0
+    puts "\nExample of a model supporting generateContent:"
+    display_model(method_models.first)
+  end
+rescue => e
+  puts "Error filtering by method: #{e.message}"
+end
+
+# Example 6: Model comparison
+puts "\n=== Example 6: Compare token limits ==="
+begin
+  all_models = Geminize.list_all_models
+
+  # Filter to models with higher token limits
+  high_capacity_models = all_models.filter_by_min_input_tokens(100_000)
+
+  puts "Models with 100k+ input token limits:"
+  high_capacity_models.each do |model|
+    puts "  - #{model.display_name}: #{model.input_token_limit} input tokens"
+  end
+rescue => e
+  puts "Error comparing models: #{e.message}"
+end
+
+puts "\n=== Examples Complete ==="