geminize 1.0.0 → 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,3 +1,23 @@
+## [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

data/README.md

@@ -11,6 +11,7 @@ A convenient and robust Ruby interface for the Google Gemini API, enabling easy
 - Embeddings generation
 - Support for streaming responses
 - Comprehensive error handling
+- Complete Models API for discovering and filtering available models
 
 ## Installation
 
@@ -56,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:
@@ -316,6 +314,45 @@ Check out these example applications to see Geminize in action:
 - [Embeddings Example](examples/embeddings.rb)
 - [Multimodal Example](examples/multimodal.rb)
 - [System Instructions Example](examples/system_instructions.rb)
+- [Models API Example](examples/models_api.rb)
+
+## Working with Models
+
+Geminize provides a comprehensive API for querying and working with available Gemini models:
+
+```ruby
+require 'geminize'
+# Assumes API key is set via environment variables (e.g., in .env)
+
+# List available models
+models = Geminize.list_models
+puts "Available models: #{models.size}"
+
+# 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"
+
+# Find models by capability
+embedding_models = Geminize.get_embedding_models
+content_models = Geminize.get_content_generation_models
+streaming_models = Geminize.get_streaming_models
+
+# Check if a model supports a specific capability
+if model.supports_content_generation?
+  puts "This model supports content generation"
+end
+
+if model.supports_embedding?
+  puts "This model supports embeddings"
+end
+
+# 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(', ')}"
+```
+
+For more comprehensive examples, see [examples/models_api.rb](examples/models_api.rb).
 
 ## Compatibility
 

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 ==="

data/lib/geminize/configuration.rb

@@ -17,7 +17,7 @@ module Geminize
     DEFAULT_MODEL = "gemini-2.0-flash"
 
     # Default embedding model
-    DEFAULT_EMBEDDING_MODEL = "embedding-001"
+    DEFAULT_EMBEDDING_MODEL = "gemini-embedding-exp-03-07"
 
     # Default timeout values (in seconds)
     DEFAULT_TIMEOUT = 30
@@ -69,9 +69,9 @@ module Geminize
     # @return [void]
     def reset!
       @api_key = ENV["GEMINI_API_KEY"]
-      @api_version = DEFAULT_API_VERSION
-      @default_model = DEFAULT_MODEL
-      @default_embedding_model = DEFAULT_EMBEDDING_MODEL
+      @api_version = ENV["GEMINI_API_VERSION"] || DEFAULT_API_VERSION
+      @default_model = ENV["GEMINI_MODEL"] || DEFAULT_MODEL
+      @default_embedding_model = ENV["GEMINI_EMBEDDING_MODEL"] || DEFAULT_EMBEDDING_MODEL
       @timeout = DEFAULT_TIMEOUT
       @open_timeout = DEFAULT_OPEN_TIMEOUT
       @streaming_timeout = DEFAULT_STREAMING_TIMEOUT

data/lib/geminize/model_info.rb

@@ -9,6 +9,9 @@ module Geminize
     # @return [Geminize::Client] The HTTP client
     attr_reader :client
 
+    # Default page size for listing models
+    DEFAULT_PAGE_SIZE = 50
+
     # Initialize a new ModelInfo instance
     # @param client [Geminize::Client, nil] The HTTP client to use
     # @param options [Hash] Additional options for the client
@@ -20,19 +23,26 @@ module Geminize
     end
 
     # List available models from the Gemini API
+    # @param page_size [Integer, nil] Number of models to return per page (max 1000)
+    # @param page_token [String, nil] Token for retrieving a specific page
     # @param force_refresh [Boolean] Force a refresh from the API instead of using cache
     # @return [Geminize::Models::ModelList] List of available models
     # @raise [Geminize::GeminizeError] If the request fails
-    def list_models(force_refresh: false)
-      cache_key = "models_list"
+    def list_models(page_size: nil, page_token: nil, force_refresh: false)
+      cache_key = "models_list_#{page_size}_#{page_token}"
 
       # Check if we have a valid cached result
       if !force_refresh && @cache[cache_key] && @cache_expiry[cache_key] > Time.now
         return @cache[cache_key]
       end
 
+      # Prepare query parameters
+      params = {}
+      params[:pageSize] = page_size if page_size
+      params[:pageToken] = page_token
+
       # Make the API request
-      response = client.get("models")
+      response = client.get("models", params)
 
       # Create a ModelList from the response
       model_list = Models::ModelList.from_api_data(response)
@@ -44,13 +54,62 @@ module Geminize
       model_list
     end
 
+    # Get all available models, handling pagination automatically
+    # @param force_refresh [Boolean] Force a refresh from the API instead of using cache
+    # @return [Geminize::Models::ModelList] Complete list of all available models
+    # @raise [Geminize::GeminizeError] If any request fails
+    def list_all_models(force_refresh: false)
+      cache_key = "all_models_list"
+
+      # Check if we have a valid cached result
+      if !force_refresh && @cache[cache_key] && @cache_expiry[cache_key] > Time.now
+        return @cache[cache_key]
+      end
+
+      all_models = []
+      page_token = nil
+
+      # Fetch first page
+      model_list = list_models(
+        page_size: DEFAULT_PAGE_SIZE,
+        page_token: page_token,
+        force_refresh: force_refresh
+      )
+      all_models.concat(model_list.models)
+
+      # Fetch additional pages if available
+      while model_list.has_more_pages?
+        page_token = model_list.next_page_token
+        model_list = list_models(
+          page_size: DEFAULT_PAGE_SIZE,
+          page_token: page_token,
+          force_refresh: force_refresh
+        )
+        all_models.concat(model_list.models)
+      end
+
+      # Create a consolidated model list
+      result = Models::ModelList.new(all_models)
+
+      # Cache the result
+      @cache[cache_key] = result
+      @cache_expiry[cache_key] = Time.now + @cache_ttl
+
+      result
+    end
+
     # Get information about a specific model
-    # @param model_id [String] The model ID to retrieve
+    # @param model_name [String] The model name to retrieve (models/{model})
     # @param force_refresh [Boolean] Force a refresh from the API instead of using cache
     # @return [Geminize::Models::Model] The model information
     # @raise [Geminize::GeminizeError] If the request fails or model is not found
-    def get_model(model_id, force_refresh: false)
-      cache_key = "model_#{model_id}"
+    def get_model(model_name, force_refresh: false)
+      # Handle both formats: "models/gemini-1.5-pro" or just "gemini-1.5-pro"
+      unless model_name.start_with?("models/")
+        model_name = "models/#{model_name}"
+      end
+
+      cache_key = "model_#{model_name}"
 
       # Check if we have a valid cached result
       if !force_refresh && @cache[cache_key] && @cache_expiry[cache_key] > Time.now
@@ -59,7 +118,7 @@ module Geminize
 
       # Make the API request
       begin
-        response = client.get("models/#{model_id}")
+        response = client.get(model_name)
 
         # Create a Model from the response
         model = Models::Model.from_api_data(response)
@@ -71,10 +130,30 @@ module Geminize
         model
       rescue Geminize::NotFoundError => e
         # Re-raise with a more descriptive message
-        raise Geminize::NotFoundError.new("Model '#{model_id}' not found", e.code, e.http_status)
+        raise Geminize::NotFoundError.new("Model '#{model_name}' not found", e.code, e.http_status)
       end
     end
 
+    # Get models that support a specific generation method
+    # @param method [String] The generation method (e.g., "generateContent", "embedContent")
+    # @param force_refresh [Boolean] Force a refresh from the API instead of using cache
+    # @return [Geminize::Models::ModelList] List of models that support the method
+    # @raise [Geminize::GeminizeError] If the request fails
+    def get_models_by_method(method, force_refresh: false)
+      all_models = list_all_models(force_refresh: force_refresh)
+      all_models.filter_by_method(method)
+    end
+
+    # Get models by base model ID
+    # @param base_model_id [String] The base model ID to filter by
+    # @param force_refresh [Boolean] Force a refresh from the API instead of using cache
+    # @return [Geminize::Models::ModelList] List of models with the specified base model ID
+    # @raise [Geminize::GeminizeError] If the request fails
+    def get_models_by_base_id(base_model_id, force_refresh: false)
+      all_models = list_all_models(force_refresh: force_refresh)
+      all_models.filter_by_base_model_id(base_model_id)
+    end
+
     # Clear all cached model information
     # @return [void]
     def clear_cache