geminize 1.1.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1b3672d83fd6ff1d0a803808ee2c6d71681053229a84b3f33e0ea8b64b78dc74
-  data.tar.gz: 79eca877306a66edcf9dd6bfa3afc3dd1b1222c6127d4391cdc077944557a3bf
+  metadata.gz: 251a4ad929a96e4773c21c159849ec415c8ee32269e3a1cda100effeda96d1ed
+  data.tar.gz: 74b958a848f75a0cf700c3751a2fb596c5a22a4a65ea9b927ead0149fef255e7
 SHA512:
-  metadata.gz: 81c4a2324a026449c00e983a2ad0f7e4e89e5d77564a62b6e7d430303eeeb129f32002f0c9a41055b4001044ec6272386ebba920e3e0565b8ac8c61f7bbc2d5d
-  data.tar.gz: 7aeb4afe504891c0849f83b04d3afc7b50fa45c1b60d6ae5ebcaea681b403e13c1bc86613694713162fff8ab220b0f447fedf808f0611fb0dbfb7476a2243148
+  metadata.gz: a1ec3f597e8f30eedf8fe12304497896ba98e7e35137d751a64f0d3430a4723db6d63997b8852e0794e44029d014408d070613a117ae0089290d0c8e852cb2bd
+  data.tar.gz: cc0de3e6fa6949894ee531092ba02c0f07a4d828540fd1bf4f0b3d8c037f7e761212e4e4cc02dc35fedd2eea0ac8446c17c1f1ff601d64b5b5bbfa847b6702a4

data/.memory_bank/activeContext.md

@@ -9,6 +9,10 @@
 - Multimodal content handling (text + images)
 - Embeddings generation
 - Streaming responses
+- Function calling capabilities
+- JSON mode for structured responses
+- Safety settings for content moderation
+- Code execution capabilities
 
 ### Key Implementation Details
 
@@ -18,6 +22,32 @@
 - System instructions for guiding model behavior
 - Generation parameters (temperature, top_k, top_p)
 - Support for stop sequences
+- Safety settings for content moderation
+
+#### Function Calling
+
+- Tool integration with Gemini API
+- Function declaration and response models
+- Support for multiple function definitions
+- Tool execution modes (AUTO, MANUAL, NONE)
+- Function result processing
+- String-based function call detection
+
+#### Code Execution
+
+- Python code generation and execution support
+- Code execution result handling
+- Support for code libraries like matplotlib, numpy, etc.
+- Tool-based code execution integration
+- Executable code response parsing
+- Code output result parsing
+
+#### JSON Mode
+
+- Structured data response handling
+- Automatic JSON parsing
+- JSON schema integration
+- Response validation
 
 #### Multimodal Support
 
@@ -69,10 +99,14 @@
 - Streaming response optimizations
 - Comprehensive documentation
 - Error handling refinements
+- Models API integration
+- Function calling support
+- Code execution capabilities
 
 ### Upcoming Features
 
-- Support for newer Gemini models
+- Additional content types (audio, PDF)
+- Caching support
 - Advanced parameter tuning
 - Additional vector operations
 - Improved conversation persistence

data/.memory_bank/progress.md

@@ -2,7 +2,7 @@
 
 ## Current Status
 
-Geminize is a functional Ruby gem providing a complete interface to the Google Gemini API. The current implementation includes all core features with a focus on stability, documentation, and ease of use.
+Geminize is a functional Ruby gem providing a complete interface to the Google Gemini API. The current implementation includes all core features with a focus on stability, documentation, and ease of use. The gem now also includes function calling, JSON mode, safety settings, and code execution features.
 
 ## Development Progress
 
@@ -15,6 +15,11 @@ Geminize is a functional Ruby gem providing a complete interface to the Google G
 - **Streaming Responses**: ✅ Complete
 - **Error Handling**: ✅ Complete
 - **Configuration System**: ✅ Complete
+- **Models API**: ✅ Complete
+- **Function Calling**: ✅ Complete
+- **JSON Mode**: ✅ Complete
+- **Safety Settings**: ✅ Complete
+- **Code Execution**: ✅ Complete
 
 ### Documentation
 
@@ -26,7 +31,7 @@ Geminize is a functional Ruby gem providing a complete interface to the Google G
 ### Testing
 
 - **Unit Tests**: ✅ Complete
-- **Integration Tests**: 🟡 Partially Complete (70%)
+- **Integration Tests**: 🟡 Partially Complete (85%)
 - **Performance Tests**: ❌ Not Started
 
 ### Deployment
@@ -50,27 +55,35 @@ Geminize is a functional Ruby gem providing a complete interface to the Google G
 - Additional embedding task types
 - Improved documentation
 
-### v1.0.0 (Planned for 2025-05-02)
+### v1.0.0 (2025-05-02)
 
 - Removed Rails-specific integration
 - Simplified usage
 - API stabilization
 
-## Upcoming Milestones
+### v1.1.0 (2025-05-02)
+
+- Support for Gemini Models API
+- Model discovery and filtering functionality
+- Pagination support
+- Improved documentation
 
-### v1.1.0 (Planned)
+### v1.2.0 (2025-05-02)
 
-- Support for latest Gemini models
-- Advanced vector operations
-- Improved streaming performance
-- Enhanced documentation
+- Added function calling capabilities
+- Added JSON mode for structured responses
+- Added safety settings for content moderation
+- Comprehensive test suite for new features
+- Updated documentation
+
+## Upcoming Milestones
 
-### v1.2.0 (Planned)
+### v1.3.0 (Planned)
 
-- Batch processing capabilities
+- Added code execution support
+- Additional content types (audio, PDF)
+- Caching mechanisms
 - Improved conversation persistence
-- Additional configuration options
-- Memory optimizations
 
 ### v2.0.0 (Planned)
 
@@ -78,3 +91,4 @@ Geminize is a functional Ruby gem providing a complete interface to the Google G
 - Advanced function calling support
 - Performance improvements
 - Additional middleware options
+- Async API support

data/.memory_bank/projectbrief.md

@@ -11,6 +11,10 @@ Geminize is a Ruby gem providing a convenient and robust interface to Google's G
 - **Conversation Management**: Maintain conversation context for chat applications
 - **Embeddings Generation**: Generate and manipulate vector representations for text
 - **Streaming Responses**: Support for efficient streaming output
+- **Models API**: Discover and filter available Gemini models
+- **Function Calling**: Enable AI models to call functions defined by developers
+- **JSON Mode**: Generate structured JSON responses for data-oriented applications
+- **Safety Settings**: Control content generation with configurable safety thresholds
 - **Error Handling**: Comprehensive error handling and validation
 
 ## Technical Foundation
@@ -19,6 +23,8 @@ Geminize is a Ruby gem providing a convenient and robust interface to Google's G
 - Faraday for HTTP client functionality
 - Support for environment-based or programmatic configuration
 - Comprehensive API for both simple and advanced use cases
+- VCR-based testing for API interactions
+- Modular design with extensible components
 
 ## Project Goals
 
@@ -27,3 +33,13 @@ Geminize is a Ruby gem providing a convenient and robust interface to Google's G
 - Maintain clean, well-documented, and idiomatic Ruby code
 - Support both simple use cases and advanced configurations
 - Enable seamless integration with various Ruby applications
+- Stay current with the latest Gemini API features and models
+
+## Current Version
+
+Version 1.2.0 implements all core features including the latest additions:
+
+- Function calling capabilities
+- JSON mode for structured responses
+- Safety settings for content moderation
+- Comprehensive Models API

data/.memory_bank/tasks.md

@@ -6,32 +6,55 @@
 
 - [ ] Review and improve YARD documentation
 - [ ] Add more code examples
-- [ ] Update README with latest features
+- [x] 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 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
+  - [x] **Code Execution Support**
+    - [x] Create code execution model classes
+    - [x] Implement code execution tools in requests
+    - [x] Update response handling for code execution
+    - [x] Add module-level code execution methods
+    - [x] Create example script 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
-- [ ] **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
+- [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
 
@@ -57,18 +80,41 @@
 - [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
 

data/CHANGELOG.md

@@ -1,3 +1,39 @@
+## [1.3.0] - 2024-05-02
+
+### Added
+
+- Code execution capabilities for generating and running Python code
+  - Added `generate_with_code_execution` method to create and execute Python code
+  - Implemented `ExecutableCode` model for representing generated code
+  - Added `CodeExecutionResult` model for capturing execution output and status
+  - Added support for visualizations and data analysis with matplotlib and other libraries
+  - Extended tool system to support code execution tools
+  - Updated content request/response handling for code execution
+  - Added comprehensive test suite with VCR tests for code execution
+  - Added examples demonstrating code execution functionality
+
+## [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

data/README.md

@@ -10,6 +10,9 @@ 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
 
@@ -273,6 +276,226 @@ 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`
+
+## Code Execution
+
+Generate and run Python code to solve problems or analyze data:
+
+```ruby
+require 'geminize'
+# Assumes API key is configured via .env
+
+# Ask Gemini to solve a problem with code
+response = Geminize.generate_with_code_execution(
+  "Calculate the sum of the first 10 prime numbers",
+  "gemini-2.0-flash", # Use a model that supports code execution
+  { temperature: 0.2 }
+)
+
+# Display the response text
+puts "Gemini's explanation:"
+puts response.text
+
+# Access the generated code
+if response.has_executable_code?
+  puts "\nGenerated Python code:"
+  puts response.executable_code.code
+end
+
+# Access the code execution result
+if response.has_code_execution_result?
+  puts "\nExecution result:"
+  puts "Outcome: #{response.code_execution_result.outcome}"
+  puts "Output: #{response.code_execution_result.output}"
+end
+```
+
+Code execution is perfect for:
+
+- Solving mathematical problems
+- Data analysis and visualization
+- Algorithm implementation
+- Demonstrating programming concepts
+
+The model generates Python code, executes it in a secure environment, and returns both the code and its execution results.
+
 ## Streaming Responses
 
 Get real-time, token-by-token responses:
@@ -315,6 +538,8 @@ Check out these example applications to see Geminize in action:
 - [Multimodal Example](examples/multimodal.rb)
 - [System Instructions Example](examples/system_instructions.rb)
 - [Models API Example](examples/models_api.rb)
+- [Function Calling Example](examples/function_calling.rb)
+- [Code Execution Example](examples/code_execution.rb)
 
 ## Working with Models