ruby-gemini-api 0.1.6 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 80e6cd429265c5341e1efcd3e701f9643cdb4785f18826234ec879178d4a236e
-  data.tar.gz: c9a9c5201b616ce2d534393c1d99240563b9d36229dac4f564f71b4ed82ee42b
+  metadata.gz: 92b2d6f35fbff3fda1457ef3244ae730ee99e156909c310b62878540d47d4076
+  data.tar.gz: 710191ae9ac4f136ea586782be43b8aa18390d74a8ba1d844a9524fc120fdaa4
 SHA512:
-  metadata.gz: b1ac2fe8cf4dacad20f21a7eab1872fa496a797b76d9af12cb401c5f563aeaed9cd58e4323334fcd6bbf67d74273902b5f9f076a5a44833474b4f3a4e8409148
-  data.tar.gz: 17693cd9f1a87ad1fdf21c26153d1ac351ca9137c99e1c97cddd2524333db21190b0bbf5c08b995939c950338f0d5bf4607263a2ae0bc92c0343b28d439c2a6f
+  metadata.gz: 31a2f84ff0f7d9d5127fe3cfa2eba75c2395cc4105e5faa6d45b472ccc4dc8e6502f28635f6a7dfce0c071e445010af9a1781c833a18c6f491f55b9e2989957b
+  data.tar.gz: 499e659d3a3284f461deede5fbcaff16ebb3476ced2c3c5c44d4d5e333d3751e45483ed221a654b0b560651127496933342e0fed5bfea8307de40edab80faa21

data/CHANGELOG.md

@@ -1,27 +1,50 @@
 ## [Unreleased]
 
-## [0.1.0] - 2025-04-05
-- Initial release
+## [1.0.0] - 2026-01-28
 
-## [0.1.1] - 2025-05-04
-- Changed generate_contents to accept temperature parameter
+### Added
+- Thinking feature support for Gemini 2.5 and Gemini 3 models
+  - `thinking_budget` parameter for Gemini 2.5 (1-32768 tokens, -1 for dynamic, 0 to disable)
+  - `thinking_level` parameter for Gemini 3 (:minimal, :low, :medium, :high)
+- Thought Signatures support for Function Calling with Thinking
+  - `FunctionCallingHelper.build_continuation` for automatic signature management
+  - Response methods: `thought_signatures`, `first_thought_signature`, `has_thought_signature?`
+- Response helper methods: `thoughts_token_count`, `model_version`, `gemini_3?`
 
-## [0.1.2] - 2025-07-10
-- Add function calling
+## [0.1.7] - 2026-01-13
 
-## [0.1.3] - 2025-10-09
-- Add support for multi-image input
-
-## [0.1.4] - 2025-11-08
-- Add support for grounding search
-
-## [0.1.5] - 2025-11-13
-- Add support for URL Context tool
-- Add simplified method for accessing grounding search sources
+- Remove dotenv dependency
 
 ## [0.1.6] - 2025-12-11
+
 - Add support for video understanding
   - Analyze local video files (Files API and inline data)
   - Analyze YouTube videos
   - Helper methods: describe, ask, extract_timestamps, analyze_segment
   - Support for MP4, MPEG, MOV, AVI, FLV, WebM, WMV, 3GPP formats
+- Change default model to gemini-2.5-flash
+
+## [0.1.5] - 2025-11-13
+
+- Add support for URL Context tool
+- Add simplified method for accessing grounding search sources
+
+## [0.1.4] - 2025-11-08
+
+- Add support for grounding search
+
+## [0.1.3] - 2025-10-09
+
+- Add support for multi-image input
+
+## [0.1.2] - 2025-07-10
+
+- Add function calling
+
+## [0.1.1] - 2025-05-04
+
+- Changed generate_contents to accept temperature parameter
+
+## [0.1.0] - 2025-04-05
+
+- Initial release

data/README.md

@@ -1,10 +1,22 @@
 [README ‐ 日本語](https://github.com/rira100000000/ruby-gemini-api/blob/main/README_ja.md)
 # Ruby-Gemini-API
 
+[![Gem Version](https://badge.fury.io/rb/ruby-gemini-api.svg)](https://badge.fury.io/rb/ruby-gemini-api)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
 A Ruby client library for Google's Gemini API. This gem provides a simple, intuitive interface for interacting with Gemini's generative AI capabilities, following patterns similar to other AI client libraries.
 
 This project is inspired by and pays homage to [ruby-openai](https://github.com/alexrudall/ruby-openai), aiming to provide a familiar and consistent experience for Ruby developers working with Gemini's AI models.
 
+## Why This Gem?
+
+- **Familiar Interface**: API design inspired by ruby-openai for a smooth transition
+- **Comprehensive Features**: Text generation, vision, audio, video, function calling, and more
+- **Response Object**: Convenient wrapper for easy access to generated content
+- **Streaming Support**: Real-time text generation with block-based API
+- **Thinking Support**: Built-in support for Gemini 2.5/3 thinking features
+- **Production Ready**: Stable 1.0 release with thorough documentation
+
 ## Features
 
 - Text generation with Gemini models
@@ -94,6 +106,105 @@ puts "After deleting a function: #{all_tools.list_functions}"
 # => After deleting a function: [:get_current_weather, :send_email]
 ```
 
+### Thinking Feature
+
+Gemini 2.5 and later models support the Thinking feature, which enables the model to perform internal reasoning processes for complex problems to generate higher-quality answers.
+
+#### Using with Gemini 2.5: `thinking_budget`
+
+```ruby
+require 'gemini'
+
+client = Gemini::Client.new(ENV['GEMINI_API_KEY'])
+
+# Specify thinking token count (1-32768)
+response = client.generate_content(
+  "Solve this complex math problem step by step",
+  model: "gemini-2.5-flash",
+  thinking_budget: 2048
+)
+
+puts "Thoughts token count: #{response.thoughts_token_count}"
+puts "Answer: #{response.text}"
+
+# Dynamic thinking (model decides automatically)
+response = client.generate_content(
+  "A difficult logic puzzle",
+  model: "gemini-2.5-flash",
+  thinking_budget: -1
+)
+
+# Disable thinking
+response = client.generate_content(
+  "Simple question",
+  thinking_budget: 0
+)
+```
+
+#### Using with Gemini 3: `thinking_level`
+
+```ruby
+# Specify thinking level (:minimal, :low, :medium, :high)
+response = client.generate_content(
+  "Complex analysis task",
+  model: "gemini-3-flash-preview",
+  thinking_level: :high
+)
+```
+
+#### Function Calling with Thinking (Thought Signatures)
+
+When using Function Calling with Gemini 3, Thought Signatures must be managed. The library automatically handles signatures for you.
+
+```ruby
+# Initial request
+response = client.generate_content(
+  "What's the weather in Tokyo?",
+  tools: tools,
+  thinking_level: :medium
+)
+
+# If function calls are present
+if response.function_calls.any?
+  # Execute the function
+  weather_data = get_weather("Tokyo")
+
+  # Build continuation request (with automatic signature attachment)
+  contents = Gemini::FunctionCallingHelper.build_continuation(
+    original_contents: [{ role: "user", parts: [{ text: "What's the weather in Tokyo?" }] }],
+    model_response: response,
+    function_responses: [
+      { name: "get_weather", response: weather_data }
+    ]
+  )
+
+  # Continuation request
+  final_response = client.generate_content(
+    contents,
+    tools: tools,
+    thinking_level: :medium
+  )
+
+  puts final_response.text
+end
+```
+
+#### Response Methods for Thinking
+
+```ruby
+# Get thoughts token count
+response.thoughts_token_count  # => 150
+
+# Get thought signatures (for Function Calling)
+response.thought_signatures    # => ["base64encoded..."]
+response.first_thought_signature
+response.has_thought_signature?
+
+# Check model version
+response.model_version  # => "gemini-3-flash-preview"
+response.gemini_3?      # => true
+```
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -1116,6 +1227,8 @@ The gem includes several demo applications that showcase its functionality:
 - `demo/file_audio_demo.rb` - Audio transcription with large audio files
 - `demo/structured_output_demo.rb` - Structured JSON output with schema
 - `demo/enum_response_demo.rb` - Enum-constrained responses
+- `demo/thinking_demo.rb` - Thinking feature (Gemini 2.5)
+- `demo/thinking_gemini3_demo.rb` - Thinking feature (Gemini 3)
 - `demo/document_chat_demo.rb` - Document processing
 - `demo/document_conversation_demo.rb` - Conversation with documents
 - `demo/document_cache_demo.rb` - Document caching
@@ -1159,6 +1272,12 @@ ruby demo/structured_output_demo.rb
 # Enum-constrained responses
 ruby demo/enum_response_demo.rb
 
+# Thinking feature (Gemini 2.5)
+ruby demo/thinking_demo.rb
+
+# Thinking feature (Gemini 3)
+ruby demo/thinking_gemini3_demo.rb
+
 # Document processing
 ruby demo/document_chat_demo.rb path/to/document.pdf
 

data/lib/gemini/client.rb

@@ -1,9 +1,10 @@
 module Gemini
   class Client
     include Gemini::HTTP
-    
+
     SENSITIVE_ATTRIBUTES = %i[@api_key @extra_headers].freeze
     CONFIG_KEYS = %i[api_key uri_base extra_headers log_errors request_timeout].freeze
+    VALID_THINKING_LEVELS = %w[minimal low medium high].freeze
     
     attr_reader(*CONFIG_KEYS, :faraday_middleware)
     attr_writer :api_key
@@ -83,7 +84,18 @@ module Gemini
     # Extended to support streaming callbacks
     def chat(parameters: {}, &stream_callback)
       model = parameters.delete(:model) || "gemini-2.5-flash"
-      
+
+      # thinking_budget / thinking_level をパラメータから抽出
+      thinking_budget = parameters.delete(:thinking_budget)
+      thinking_level = parameters.delete(:thinking_level)
+
+      # Thinking設定
+      thinking_config = build_thinking_config(thinking_budget, thinking_level)
+      if thinking_config
+        parameters[:generationConfig] ||= {}
+        parameters[:generationConfig][:thinkingConfig] = thinking_config
+      end
+
       # If streaming callback is provided
       if block_given?
         path = "models/#{model}:streamGenerateContent"
@@ -121,10 +133,12 @@ module Gemini
     
     # Helper methods for convenience
     
-        # Method with usage similar to OpenAI's chat
+    # Method with usage similar to OpenAI's chat
     def generate_content(prompt, model: "gemini-2.5-flash", system_instruction: nil,
                         response_mime_type: nil, response_schema: nil, temperature: 0.5, tools: nil,
-                        url_context: false, google_search: false, **parameters, &stream_callback)
+                        url_context: false, google_search: false,
+                        thinking_budget: nil, thinking_level: nil,
+                        **parameters, &stream_callback)
       content = format_content(prompt)
       params = {
         contents: [content],
@@ -144,6 +158,12 @@ module Gemini
         params[:generation_config]["response_schema"] = response_schema
       end
 
+      # Thinking設定を追加
+      thinking_config = build_thinking_config(thinking_budget, thinking_level)
+      if thinking_config
+        params[:generation_config][:thinkingConfig] = thinking_config
+      end
+
       # Handle tool shortcuts
       tools = build_tools_array(tools, url_context: url_context, google_search: google_search)
       params[:tools] = tools if tools && !tools.empty?
@@ -416,6 +436,39 @@ module Gemini
     
     private
 
+    # Build thinking config from budget and level options
+    def build_thinking_config(budget, level)
+      return nil unless budget || level
+
+      config = {}
+
+      if budget
+        validate_thinking_budget!(budget)
+        config[:thinkingBudget] = budget
+      end
+
+      if level
+        level_str = level.to_s
+        validate_thinking_level!(level_str)
+        config[:thinkingLevel] = level_str
+      end
+
+      config
+    end
+
+    def validate_thinking_budget!(budget)
+      return if budget == -1 || budget == 0
+      unless budget.is_a?(Integer) && budget > 0 && budget <= 32768
+        raise ArgumentError, "thinking_budget must be -1, 0, or 1-32768"
+      end
+    end
+
+    def validate_thinking_level!(level)
+      unless VALID_THINKING_LEVELS.include?(level)
+        raise ArgumentError, "thinking_level must be one of: #{VALID_THINKING_LEVELS.join(', ')}"
+      end
+    end
+
     # Build tools array from explicit tools parameter and shortcuts
     def build_tools_array(tools, url_context: false, google_search: false)
       result_tools = []

data/lib/gemini/function_calling_helper.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Gemini
+  module FunctionCallingHelper
+    # Function Callレスポンスから継続用のcontentsを構築
+    # Gemini 3では関数呼び出しの継続時にThought Signatureが必須
+    #
+    # @param original_contents [Array] 元の会話履歴
+    # @param model_response [Gemini::Response] モデルの応答（function call含む）
+    # @param function_responses [Array<Hash>] 関数の結果の配列
+    #   各要素は { name: "function_name", response: { ... } } の形式
+    # @return [Array] 継続リクエスト用のcontents配列
+    #
+    # @example
+    #   contents = Gemini::FunctionCallingHelper.build_continuation(
+    #     original_contents: [{ role: "user", parts: [{ text: "東京の天気を教えて" }] }],
+    #     model_response: response,
+    #     function_responses: [
+    #       { name: "get_weather", response: { temperature: 20, condition: "晴れ" } }
+    #     ]
+    #   )
+    def self.build_continuation(original_contents:, model_response:, function_responses:)
+      # 元の会話履歴
+      contents = original_contents.dup
+
+      # モデルの応答（Signature付き）
+      contents << {
+        role: "model",
+        parts: model_response.build_function_call_parts_with_signature
+      }
+
+      # 関数の結果
+      function_response_parts = function_responses.map do |fr|
+        { functionResponse: fr }
+      end
+
+      contents << {
+        role: "user",
+        parts: function_response_parts
+      }
+
+      contents
+    end
+  end
+end

data/lib/gemini/response.rb

@@ -223,7 +223,52 @@ module Gemini
     def safety_ratings
       first_candidate&.dig("safetyRatings") || []
     end
-    
+
+    # Thinking関連メソッド
+
+    # 思考トークン数を取得
+    def thoughts_token_count
+      @raw_data.dig('usageMetadata', 'thoughtsTokenCount')
+    end
+
+    # Thought Signatureを取得（配列）
+    def thought_signatures
+      parts.filter_map { |p| p['thoughtSignature'] }
+    end
+
+    # 最初のThought Signatureを取得
+    def first_thought_signature
+      thought_signatures.first
+    end
+
+    # Signatureが存在するか
+    def has_thought_signature?
+      !thought_signatures.empty?
+    end
+
+    # モデルバージョンを取得
+    def model_version
+      @raw_data['modelVersion']
+    end
+
+    # Gemini 3系かどうか
+    def gemini_3?
+      model_version&.start_with?('gemini-3') || false
+    end
+
+    # 関数呼び出しにSignatureを付与してパーツを構築
+    def build_function_call_parts_with_signature
+      function_call_parts = parts.select { |p| p['functionCall'] }
+      signature = first_thought_signature
+
+      function_call_parts.map.with_index do |part, index|
+        fc_part = { functionCall: part['functionCall'] }
+        # 最初のパートにのみSignatureを付与
+        fc_part[:thoughtSignature] = signature if index == 0 && signature
+        fc_part
+      end
+    end
+
     # 画像生成結果から最初の画像を取得（Base64エンコード形式）
     def image
       images.first

data/lib/gemini/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Gemini
-  VERSION = "0.1.6"
+  VERSION = "1.0.0"
 end

data/lib/gemini.rb

@@ -1,10 +1,9 @@
 require "faraday"
 require "faraday/multipart"
 require "json"
-require 'dotenv/load'
 
-require_relative 'gemini/version'
-require_relative 'gemini/tool_definition'
+require_relative "gemini/version"
+require_relative "gemini/tool_definition"
 require_relative "gemini/http_headers"
 require_relative "gemini/http"
 require_relative "gemini/client"
@@ -17,9 +16,11 @@ require_relative "gemini/audio"
 require_relative "gemini/files"
 require_relative "gemini/images"
 require_relative "gemini/response"
+require_relative "gemini/function_calling_helper"
 require_relative "gemini/documents"
 require_relative "gemini/cached_content"
 require_relative "gemini/video"
+
 module Gemini
   class Error < StandardError; end
   class ConfigurationError < Error; end
@@ -27,28 +28,29 @@ module Gemini
   class APIError < Error; end
   class RateLimitError < Error; end
   class InvalidRequestError < Error; end
-  
+
   class MiddlewareErrors < Faraday::Middleware
     def call(env)
       @app.call(env)
     rescue Faraday::Error => e
       raise e unless e.response.is_a?(Hash)
+
       Gemini.log_message("Gemini HTTP Error", e.response[:body], :error)
       raise e
     end
   end
-  
+
   class Configuration
     attr_accessor :api_key,
                   :uri_base,
                   :log_errors,
                   :request_timeout,
                   :extra_headers
-                  
+
     DEFAULT_URI_BASE = "https://generativelanguage.googleapis.com/v1beta".freeze
     DEFAULT_REQUEST_TIMEOUT = 120
     DEFAULT_LOG_ERRORS = false
-    
+
     def initialize
       @api_key = nil
       @log_errors = DEFAULT_LOG_ERRORS
@@ -57,21 +59,21 @@ module Gemini
       @extra_headers = {}
     end
   end
-  
+
   class << self
     attr_writer :configuration
-    
+
     def configuration
       @configuration ||= Gemini::Configuration.new
     end
-    
+
     def configure
       yield(configuration)
     end
-    
+
     def log_message(prefix, message, level = :warn)
       return unless configuration.log_errors
-      
+
       color = level == :error ? "\033[31m" : "\033[33m"
       logger = Logger.new($stdout)
       logger.formatter = proc do |_severity, _datetime, _progname, msg|
@@ -80,4 +82,4 @@ module Gemini
       logger.send(level, message)
     end
   end
-end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby-gemini-api
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 1.0.0
 platform: ruby
 authors:
 - rira100000000
@@ -152,6 +152,7 @@ files:
 - lib/gemini/documents.rb
 - lib/gemini/embeddings.rb
 - lib/gemini/files.rb
+- lib/gemini/function_calling_helper.rb
 - lib/gemini/http.rb
 - lib/gemini/http_headers.rb
 - lib/gemini/images.rb