geminize 1.0.0 → 1.2.0

data/.memory_bank/systemPatterns.md

@@ -0,0 +1,90 @@
+# System Patterns
+
+## Design Patterns
+
+### Singleton Pattern
+
+- Used for the `Configuration` class to ensure a single global configuration instance.
+- Implemented using Ruby's `Singleton` module.
+
+### Builder Pattern
+
+- Employed in `RequestBuilder` to construct API requests.
+- Separates request construction from execution.
+
+### Factory Methods
+
+- Used throughout the codebase to instantiate model objects from API responses.
+- Example: `Models::ContentResponse.from_hash(response_data)`
+
+### Repository Pattern
+
+- Implemented in `ConversationRepository` for conversation persistence.
+- Abstracts storage details from the conversation service.
+
+### Adapter Pattern
+
+- Used to adapt various image sources (files, URLs, raw bytes) to a common format.
+
+### Strategy Pattern
+
+- Applied in streaming responses with different processing modes (raw, incremental, delta).
+- Allows clients to choose how streaming data is processed.
+
+## Core Architectural Principles
+
+### Separation of Concerns
+
+- Each class has a single, well-defined responsibility.
+- Examples: `Client` handles HTTP, `TextGeneration` handles generation logic.
+
+### Immutable Objects
+
+- Response objects are designed to be immutable.
+- Request objects are built incrementally but not modified after submission.
+
+### Comprehensive Validation
+
+- Input validation happens before API calls.
+- Extensive parameter checking and error handling.
+
+### Error Handling
+
+- Structured hierarchy of error classes.
+- Detailed error messages with relevant context.
+- Translation of API errors to gem-specific errors.
+
+### Configuration Flexibility
+
+- Multiple configuration approaches (env vars, block config).
+- Sensible defaults with override capabilities.
+
+### Developer Experience
+
+- Method signatures follow Ruby idioms.
+- Clear documentation with usage examples.
+- Consistent return values and error handling.
+
+## Code Organization
+
+### Module Structure
+
+- Everything contained within the `Geminize` namespace.
+- Logical grouping of related functionality.
+
+### Dependency Management
+
+- Minimal external dependencies.
+- Clear version requirements.
+
+### Testing Approach
+
+- RSpec for unit and integration tests.
+- VCR for recording and replaying HTTP interactions.
+- Comprehensive test coverage.
+
+### Documentation
+
+- YARD documentation for all public methods.
+- Usage examples throughout codebase.
+- Clear README with quickstart and detailed examples.

data/.memory_bank/tasks.md

@@ -0,0 +1,142 @@
+# Tasks
+
+## Current Tasks
+
+### Documentation
+
+- [ ] Review and improve YARD documentation
+- [ ] Add more code examples
+- [x] Update README with latest features
+- [ ] Create diagrams for architecture overview
+
+### Feature Development
+
+- [ ] Support for new Gemini models as they become available
+- [ ] Implement Gemini API missing features:
+  - [x] **Function Calling Support**
+    - [x] Create model classes for function calling structures
+    - [x] Update ContentRequest to support tools and functions
+    - [x] Update request builder and response handling
+    - [x] Add module-level convenience methods
+    - [x] Add comprehensive VCR tests for function calling
+  - [x] **JSON Mode Support**
+    - [x] Add MIME type support for JSON responses
+    - [x] Implement helper methods for JSON generation
+    - [x] Add validation for JSON response structures
+    - [x] Add tests for JSON mode functionality
+  - [x] **Safety Settings**
+    - [x] Create SafetySetting model
+    - [x] Add safety configuration to requests
+    - [x] Implement module-level safety methods
+    - [x] Add tests for safety settings
+  - [ ] **Code Execution Support**
+    - [ ] Create code execution model classes
+    - [ ] Implement code execution tools in requests
+    - [ ] Update response handling for code execution
+  - [ ] **Additional Content Types**
+    - [ ] Audio content support
+    - [ ] Document/PDF content support
+    - [ ] Video content support
+  - [ ] **Caching Support**
+    - [ ] Add caching to content requests
+    - [ ] Implement cached content handling
+    - [ ] Add module-level caching methods
+- [x] Add support for function calling capabilities
+- [ ] Implement batch embedding generation
+- [ ] Improve conversation persistence with adapter pattern for multiple storage options
+
+### Testing
+
+- [ ] Expand test coverage
+- [ ] Add integration tests for streaming
+- [x] Update VCR cassettes with latest API responses
+- [ ] Add benchmarks for performance testing
+- [x] Create test fixtures for new Gemini API features
+- [x] Add VCR cassettes for function calling responses
+
+### 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
+  - [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
+- [x] Function Calling Support
+  - [x] Create function declaration, tool, and response models
+  - [x] Implement request and response extensions
+  - [x] Add module-level methods for function calling
+  - [x] Add VCR tests for real API interactions
+- [x] JSON Mode Support
+  - [x] Add MIME type support and JSON response parsing
+  - [x] Add structured data generation features
+- [x] Safety Settings Support
+  - [x] Implement safety categories and thresholds
+  - [x] Add safety-focused generation methods
+
+### Documentation
+
+- [x] Initial README with examples
+- [x] YARD documentation for public methods
+- [x] Example scripts
+- [x] Update README with function calling, JSON mode, and safety settings
+
+### Testing
+
+- [x] Basic test suite with RSpec
+- [x] VCR setup for API mocking
+- [x] Unit tests for core functionality
+- [x] Integration tests for function calling
+- [x] Tests for JSON mode and safety settings
+
+### 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,45 @@
+## [1.2.0] - 2025-05-02
+
+### Added
+
+- Function calling capabilities for working with the Gemini API's tool features
+  - Added `generate_with_functions` method to create content with function definitions
+  - Added `process_function_call` method to handle function responses
+  - Added support for multiple function declarations in a single request
+  - Added configurable tool execution modes (AUTO, MANUAL, NONE)
+  - Implemented comprehensive test suite for function calling features
+  - Added tool-related model classes (Tool, ToolConfig, FunctionDeclaration, FunctionResponse)
+- JSON mode for structured data responses
+  - Added `generate_json` method for receiving JSON-formatted responses
+  - Implemented automatic parsing of JSON responses
+  - Added type-checking and validation for JSON mode configuration
+- Safety settings for controlled content generation
+  - Added `generate_with_safety_settings` method for customizing safety settings
+  - Added `generate_text_safe` for maximum content safety
+  - Added `generate_text_permissive` for minimum content filtering
+  - Added comprehensive safety categories and threshold levels
+  - Implemented validation for safety setting configurations
+
+## [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

@@ -10,7 +10,11 @@ A convenient and robust Ruby interface for the Google Gemini API, enabling easy
 - Multimodal inputs (text + images)
 - Embeddings generation
 - Support for streaming responses
+- Function calling capabilities for tool integration
+- JSON mode for structured data responses
+- Safety settings for content moderation
 - Comprehensive error handling
+- Complete Models API for discovering and filtering available models
 
 ## Installation
 
@@ -56,11 +60,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:
@@ -275,6 +276,184 @@ end
 
 See the `examples/embeddings.rb` file for more comprehensive examples of working with embeddings.
 
+## Function Calling
+
+Geminize provides support for Gemini's function calling capabilities, allowing the AI model to call functions defined by you:
+
+```ruby
+require 'geminize'
+# Assumes API key is configured via .env
+
+# Define functions that the model can call
+weather_functions = [
+  {
+    name: "get_weather",
+    description: "Get the current weather for a location",
+    parameters: {
+      type: "object",
+      properties: {
+        location: {
+          type: "string",
+          description: "The city and state, e.g. New York, NY"
+        },
+        unit: {
+          type: "string",
+          enum: ["celsius", "fahrenheit"],
+          description: "The unit of temperature"
+        }
+      },
+      required: ["location"]
+    }
+  }
+]
+
+# Generate a response that may include a function call
+response = Geminize.generate_with_functions(
+  "What's the weather in San Francisco?",
+  weather_functions,
+  "gemini-1.5-pro", # Make sure you use a model that supports function calling
+  {
+    temperature: 0.2,
+    system_instruction: "Use the provided function to get weather information."
+  }
+)
+
+# Check if the response contains a function call
+if response.has_function_call?
+  function_call = response.function_call
+  puts "Function called: #{function_call.name}"
+  puts "Arguments: #{function_call.response.inspect}"
+
+  # Process the function call with your implementation
+  final_response = Geminize.process_function_call(response) do |name, args|
+    if name == "get_weather"
+      location = args["location"]
+      # Call your actual weather API here
+      # For this example, we'll just return mock data
+      {
+        temperature: 72,
+        conditions: "partly cloudy",
+        humidity: 65,
+        location: location
+      }
+    end
+  end
+
+  # Display the final response
+  puts "Final response: #{final_response.text}"
+else
+  puts "No function call in response: #{response.text}"
+end
+```
+
+### Function Call Options
+
+You can customize function calling behavior:
+
+```ruby
+# Set the tool execution mode:
+# - "AUTO": Model decides when to call functions
+# - "MANUAL": Functions are only used when explicitly requested
+# - "NONE": Functions are ignored
+response = Geminize.generate_with_functions(
+  prompt,
+  functions,
+  model_name,
+  { tool_execution_mode: "MANUAL" }
+)
+
+# Control retry behavior
+response = Geminize.generate_with_functions(
+  prompt,
+  functions,
+  model_name,
+  with_retries: false # Disable automatic retries on failure
+)
+```
+
+## JSON Mode
+
+Generate structured JSON responses from the model:
+
+```ruby
+require 'geminize'
+# Assumes API key is configured via .env
+
+# Request JSON-formatted data
+response = Geminize.generate_json(
+  "List the three largest planets in our solar system with their diameters in km",
+  "gemini-1.5-pro", # Use a model that supports JSON mode
+  { temperature: 0.2 }
+)
+
+# Access the parsed JSON data
+if response.has_json_response?
+  planets = response.json_response
+  puts "Received structured data:"
+  planets.each do |planet|
+    puts "#{planet['name']}: #{planet['diameter']} km"
+  end
+else
+  puts "No valid JSON in response: #{response.text}"
+end
+```
+
+The JSON mode is ideal for getting structured data that you can programmatically process in your application.
+
+## Safety Settings
+
+Control content generation with safety settings:
+
+```ruby
+require 'geminize'
+# Assumes API key is configured via .env
+
+# Generate content with custom safety settings
+safety_settings = [
+  { category: "HARM_CATEGORY_DANGEROUS_CONTENT", threshold: "BLOCK_MEDIUM_AND_ABOVE" },
+  { category: "HARM_CATEGORY_HATE_SPEECH", threshold: "BLOCK_LOW_AND_ABOVE" }
+]
+
+response = Geminize.generate_with_safety_settings(
+  "Explain the concept of nuclear fission",
+  safety_settings,
+  "gemini-1.5-pro",
+  { temperature: 0.7 }
+)
+
+puts response.text
+
+# For maximum safety (blocks most potentially harmful content)
+safe_response = Geminize.generate_text_safe(
+  "Tell me about controversial political topics",
+  "gemini-1.5-pro"
+)
+
+puts "Safe response: #{safe_response.text}"
+
+# For minimum filtering (blocks only the most harmful content)
+permissive_response = Geminize.generate_text_permissive(
+  "Describe a controversial historical event",
+  "gemini-1.5-pro"
+)
+
+puts "Permissive response: #{permissive_response.text}"
+```
+
+Available safety categories:
+
+- `HARM_CATEGORY_HATE_SPEECH`
+- `HARM_CATEGORY_DANGEROUS_CONTENT`
+- `HARM_CATEGORY_HARASSMENT`
+- `HARM_CATEGORY_SEXUALLY_EXPLICIT`
+
+Available threshold levels (from most to least restrictive):
+
+- `BLOCK_LOW_AND_ABOVE`
+- `BLOCK_MEDIUM_AND_ABOVE`
+- `BLOCK_ONLY_HIGH`
+- `BLOCK_NONE`
+
 ## Streaming Responses
 
 Get real-time, token-by-token responses:
@@ -316,6 +495,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