llm_conductor 1.8.2 → 1.8.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8a13bccd45a0d886de6bc88a531724a2e929912d21564f5c50296c000c28476a
-  data.tar.gz: 1838b42538d448dc2373b1e7e9180b92b1f97fe87dfd8b50b18a164ac992ffae
+  metadata.gz: 669ae889bc5b65b4455617425a5c3628a66ed21741eca0930c78652f4b8bfbad
+  data.tar.gz: 396219406bf2db7236c223cc36200dc1be2739d6a87ab6cc50ccdc75be7482ff
 SHA512:
-  metadata.gz: aeac7323ebde9d6327f9e536876d42f951d5e042f37888f6d0cb0dc64aaa50fd820c94cf4788a6ebde8b9e27423d67872f99a87c6ff6400f910cb07fbf37cfbc
-  data.tar.gz: 20dcb4c95317a32eaa033bbf0dadfdfa3aef5934818fbc491fd13b9e467edbe5a2b332d3234ee9f7b7181900a0a35294d356417c759c5cb736a476592ac670cf
+  metadata.gz: 9e71aaa12abdf4c1bf1d750f4e28b41508d5e0b999d8373858e5ad0a16d8ea7f24c059553e59b5b38377b262bd5e6963f0a424b745d9f58e064d4135d4c05779
+  data.tar.gz: 2ab40251e03a5b8eb01bb6d7cfdbe0bac4b1137768b4c42b991da8649ec146698d17e012d076aa102643e37ddaa94951552e8e0c8f80b68ac14fd7875f7e8cdd

data/README.md

@@ -108,7 +108,7 @@ end
 |----------|-------------|--------|---------------|
 | OpenAI (GPT) | ✅ `gpt-*` | ✅ | 🔜 |
 | Anthropic (Claude) | ✅ `claude-*` | ✅ | 🔜 |
-| Google (Gemini) | ✅ `gemini-*` | ✅ | 🔜 |
+| Google (Gemini) | ✅ `gemini-*` | ✅ | ✅ |
 | Groq | ✅ `llama/mixtral` | ❌ | 🔜 |
 | Ollama | ✅ (default) | ❌ | ✅ |
 | OpenRouter | 🔧 Manual | ✅ | 🔜 |
@@ -150,6 +150,20 @@ response = LlmConductor.generate(
 )
 ```
 
+### Fast Gemini Calls (Minimal Thinking)
+
+```ruby
+response = LlmConductor.generate(
+  model: 'gemini-3.5-flash-lite',
+  prompt: 'Extract the company name from: ...',
+  vendor: :gemini,
+  params: { thinking_level: 'minimal' }
+)
+```
+
+Sent to Gemini as `generationConfig.thinkingConfig.thinkingLevel`. See
+[Custom Parameters](docs/custom-parameters.md#gemini-thinking-configuration).
+
 ### Vision Analysis
 
 ```ruby
@@ -328,6 +342,7 @@ Check the [examples/](examples/) directory for comprehensive examples:
 
 - `simple_usage.rb` - Basic text generation
 - `ollama_params_usage.rb` - Custom parameters with Ollama
+- `gemini_thinking_usage.rb` - Gemini thinking configuration (`thinkingConfig`)
 - `gpt_vision_usage.rb` - Vision with OpenAI
 - `claude_vision_usage.rb` - Vision with Anthropic
 - `gemini_vision_usage.rb` - Vision with Gemini

data/docs/README.md

@@ -11,8 +11,8 @@ Learn how to fine-tune LLM generation with parameters like `temperature`, `top_p
 - Provider-specific parameters
 - Best practices and use cases
 
-**Currently supported**: Ollama  
-**Coming soon**: OpenAI, Anthropic, Gemini, Groq, OpenRouter, Z.ai
+**Currently supported**: Ollama, Gemini (including Gemini 3.x `thinkingConfig`)  
+**Coming soon**: OpenAI, Anthropic, Groq, OpenRouter, Z.ai
 
 ### [Vision Support](vision-support.md)
 Complete guide to using vision/multimodal capabilities. Includes:

data/docs/custom-parameters.md

@@ -149,6 +149,13 @@ Below are common parameters supported by Google Gemini via `generationConfig`. F
 | `max_output_tokens` | `maxOutputTokens` | Integer | Alias for max_tokens |
 | `candidate_count` | `candidateCount` | Integer | Number of candidates to return |
 | `stop_sequences` | `stopSequences` | Array | Stop sequences that end generation |
+| `thinking_config` | `thinkingConfig` | Hash | Gemini 3.x thinking controls (see below) |
+| `thinking_level` | `thinkingConfig.thinkingLevel` | String | Thinking depth: `'minimal'`, `'low'`, `'high'` |
+| `thinking_budget` | `thinkingConfig.thinkingBudget` | Integer | Token budget for thinking (`0` disables it) |
+| `include_thoughts` | `thinkingConfig.includeThoughts` | Boolean | Return the thought summary alongside the answer |
+
+Unsupported keys are skipped and logged as a warning through
+`LlmConductor.configuration.logger` — they are never dropped silently.
 
 ### Gemini Usage Examples
 
@@ -170,6 +177,36 @@ response = LlmConductor.generate(
 )
 ```
 
+### Gemini Thinking Configuration
+
+Gemini 3.x models think before answering. Cutting that budget down is the single
+biggest latency lever available on the fast models, so the thinking controls are
+exposed through the same `params` hash:
+
+```ruby
+# Fastest path — minimal thinking (flat convenience key)
+response = LlmConductor.generate(
+  model: 'gemini-3.5-flash-lite',
+  prompt: 'Extract the company name from: ...',
+  vendor: :gemini,
+  params: { thinking_level: 'minimal', temperature: 0.0 }
+)
+
+# Nested form — mirrors the API shape, accepts snake_case or camelCase
+response = LlmConductor.generate(
+  model: 'gemini-3.5-flash-lite',
+  prompt: 'Extract the company name from: ...',
+  vendor: :gemini,
+  params: { thinking_config: { thinking_level: 'minimal', thinking_budget: 0 } }
+)
+```
+
+Both forms are merged into the request as:
+
+```json
+{ "generationConfig": { "thinkingConfig": { "thinkingLevel": "minimal" } } }
+```
+
 ## Ollama Parameters Reference
 
 Below are common parameters supported by Ollama. For a complete list, see the [Ollama documentation](https://github.com/ollama/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values).
@@ -348,7 +385,8 @@ Always refer to your provider's documentation for supported parameters.
 
 Currently, custom parameters are fully supported for:
 - ✅ **Ollama**
-- ✅ **Google (Gemini)** — maps snake_case Ruby keys to camelCase `generationConfig`
+- ✅ **Google (Gemini)** — maps snake_case Ruby keys to camelCase `generationConfig`,
+  including `thinkingConfig` for Gemini 3.x thinking controls
 
 Coming soon:
 - 🔜 OpenAI (GPT)
@@ -364,6 +402,8 @@ Coming soon:
 1. Check parameter spelling (case-sensitive)
 2. Verify your provider supports the parameter
 3. Check parameter value types (integer vs float vs string)
+4. Set `config.logger` — Gemini logs a warning for every param it cannot map,
+   e.g. `Skipping generationConfig param :reasoning_effort: no Gemini API mapping.`
 
 ### Unexpected Output
 
@@ -379,7 +419,9 @@ Coming soon:
 
 ## Examples
 
-See the complete example file: [examples/ollama_params_usage.rb](examples/ollama_params_usage.rb)
+See the complete example files:
+- [examples/ollama_params_usage.rb](../examples/ollama_params_usage.rb)
+- [examples/gemini_thinking_usage.rb](../examples/gemini_thinking_usage.rb)
 
 ## Resources
 

data/examples/gemini_thinking_usage.rb

@@ -0,0 +1,48 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Gemini thinking configuration (generationConfig.thinkingConfig).
+#
+# Gemini 3.x models think before answering. Trimming that budget is the biggest
+# latency lever on the fast models, so llm_conductor exposes it through params:
+#
+#   params: { thinking_level: 'minimal' }                       # flat convenience key
+#   params: { thinking_config: { thinking_level: 'minimal' } }  # nested, mirrors the API
+#
+# Both reach the API as generationConfig.thinkingConfig.thinkingLevel.
+#
+#   GEMINI_API_KEY=... ruby examples/gemini_thinking_usage.rb
+#   GEMINI_API_KEY=... MODEL=gemini-3.5-flash-lite ruby examples/gemini_thinking_usage.rb
+
+require_relative '../lib/llm_conductor'
+require 'logger'
+
+MODEL = ENV['MODEL'] || 'gemini-2.5-flash'
+PROMPT = 'Name the capital of France. Answer with one word.'
+
+LlmConductor.configure do |config|
+  config.gemini(api_key: ENV.fetch('GEMINI_API_KEY'))
+  # With a logger configured, any param the client cannot map is reported
+  # instead of being dropped silently.
+  config.logger = Logger.new($stdout)
+end
+
+CASES = {
+  'no thinking config' => {},
+  'flat thinking_level' => { thinking_level: 'minimal' },
+  'nested thinking_config' => { thinking_config: { thinking_level: 'minimal' } },
+  'thinking_budget: 0' => { thinking_config: { thinking_budget: 0 } },
+  'unmapped param (expect a warning)' => { reasoning_effort: 'high' }
+}.freeze
+
+CASES.each do |label, params|
+  started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  response = LlmConductor.generate(model: MODEL, prompt: PROMPT, vendor: :gemini, params:)
+  elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+
+  if response.success?
+    puts "[#{label}] #{elapsed.round(2)}s — #{response.output.to_s.strip}"
+  else
+    puts "[#{label}] FAILED — #{response.metadata[:error]}"
+  end
+end

data/lib/llm_conductor/clients/concerns/gemini_generation_config.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module LlmConductor
+  module Clients
+    module Concerns
+      # Builds Gemini's generationConfig payload from the generic snake_case +params+
+      # hash accepted by every client.
+      #
+      # The Gemini REST API expects camelCase keys inside generationConfig, and nests
+      # the Gemini 3.x thinking controls one level deeper, under
+      # generationConfig.thinkingConfig. Callers keep passing snake_case Ruby keys —
+      # the translation lives here.
+      #
+      # Keys without a mapping are skipped and reported through the configured logger
+      # instead of disappearing silently. Skipping rather than raising keeps existing
+      # callers that pass provider-agnostic params working unchanged.
+      module GeminiGenerationConfig
+        # Gemini REST API uses camelCase keys in generationConfig.
+        PARAM_KEY_MAP = {
+          temperature: :temperature,
+          top_p: :topP,
+          top_k: :topK,
+          max_tokens: :maxOutputTokens,
+          max_output_tokens: :maxOutputTokens,
+          candidate_count: :candidateCount,
+          stop_sequences: :stopSequences
+        }.freeze
+
+        # Keys nested under generationConfig.thinkingConfig (Gemini 3.x thinking
+        # controls). Accepted flat in params or inside a thinking_config hash.
+        THINKING_KEY_MAP = {
+          thinking_level: :thinkingLevel,
+          thinking_budget: :thinkingBudget,
+          include_thoughts: :includeThoughts
+        }.freeze
+
+        # Param keys carrying a nested thinkingConfig hash.
+        THINKING_CONFIG_KEYS = %i[thinking_config thinkingConfig].freeze
+
+        private
+
+        # Build Gemini generationConfig from the params hash.
+        #
+        # Thinking controls may be passed flat (thinking_level: 'minimal') or nested
+        # (thinking_config: { thinking_level: 'minimal' }); either way they end up in
+        # generationConfig.thinkingConfig, and both forms together are merged.
+        #
+        # @return [Hash, nil] generationConfig hash, or nil when nothing maps
+        def build_generation_config
+          return unless params.is_a?(Hash) && params.any?
+
+          gen_cfg = {}
+          thinking_cfg = {}
+          params.each { |key, value| assign_generation_param(key, value, gen_cfg, thinking_cfg) }
+          gen_cfg[:thinkingConfig] = thinking_cfg if thinking_cfg.any?
+          gen_cfg.any? ? gen_cfg : nil
+        end
+
+        # Route a single param into generationConfig or its nested thinkingConfig.
+        def assign_generation_param(key, value, gen_cfg, thinking_cfg)
+          if THINKING_CONFIG_KEYS.include?(key.to_sym)
+            thinking_cfg.merge!(normalize_thinking_config(value))
+          elsif (thinking_key = thinking_config_key_for(key))
+            thinking_cfg[thinking_key] = value
+          elsif (mapped = PARAM_KEY_MAP[key.to_sym])
+            gen_cfg[mapped] = value
+          else
+            warn_unmapped_param(key)
+          end
+        end
+
+        # Normalize a nested thinking_config hash to the API's camelCase keys.
+        # @param value [Hash] thinking config as given by the caller
+        # @return [Hash] camelCase thinkingConfig fragment
+        def normalize_thinking_config(value)
+          unless value.is_a?(Hash)
+            warn_unmapped_param(:thinking_config, reason: "expected a Hash, got #{value.class}")
+            return {}
+          end
+
+          value.each_with_object({}) do |(key, val), cfg|
+            mapped = thinking_config_key_for(key)
+            if mapped
+              cfg[mapped] = val
+            else
+              warn_unmapped_param(key, scope: 'thinkingConfig')
+            end
+          end
+        end
+
+        # Resolve a thinkingConfig key, accepting snake_case or the camelCase API name.
+        # @return [Symbol, nil] camelCase API key, or nil when unknown
+        def thinking_config_key_for(key)
+          sym_key = key.to_sym
+          THINKING_KEY_MAP[sym_key] || (sym_key if THINKING_KEY_MAP.value?(sym_key))
+        end
+
+        # Report a param the client cannot map. Non-fatal by design: unmapped keys are
+        # skipped, but never without a trace — configure LlmConductor.configuration.logger
+        # to surface them.
+        def warn_unmapped_param(key, scope: 'generationConfig', reason: 'no Gemini API mapping')
+          configuration.logger&.warn(
+            "[LlmConductor::Clients::GeminiClient] Skipping #{scope} param #{key.inspect}: #{reason}. " \
+            'See docs/custom-parameters.md for the supported keys.'
+          )
+        end
+      end
+    end
+  end
+end

data/lib/llm_conductor/clients/gemini_client.rb

@@ -5,6 +5,7 @@ require 'base64'
 require 'net/http'
 require 'uri'
 require_relative 'concerns/vision_support'
+require_relative 'concerns/gemini_generation_config'
 require_relative '../patches/gemini_vertex_api_key'
 
 module LlmConductor
@@ -13,20 +14,10 @@ module LlmConductor
     # Supports both text-only and multimodal (vision) requests
     class GeminiClient < BaseClient
       include Concerns::VisionSupport
+      include Concerns::GeminiGenerationConfig
 
       private
 
-      # Gemini REST API uses camelCase keys in generationConfig.
-      PARAM_KEY_MAP = {
-        temperature: :temperature,
-        top_p: :topP,
-        top_k: :topK,
-        max_tokens: :maxOutputTokens,
-        max_output_tokens: :maxOutputTokens,
-        candidate_count: :candidateCount,
-        stop_sequences: :stopSequences
-      }.freeze
-
       def generate_content(prompt)
         content = format_content(prompt)
         parts = build_parts_for_gemini(content)
@@ -45,20 +36,6 @@ module LlmConductor
         response.dig('candidates', 0, 'content', 'parts', 0, 'text')
       end
 
-      # Build Gemini generationConfig from params hash.
-      # Maps snake_case Ruby keys to camelCase Gemini API keys.
-      # @return [Hash, nil] generationConfig hash or nil if no mapped params
-      def build_generation_config
-        return unless params.is_a?(Hash) && params.any?
-
-        gen_cfg = {}
-        params.each do |key, value|
-          mapped = PARAM_KEY_MAP[key.to_sym]
-          gen_cfg[mapped] = value if mapped
-        end
-        gen_cfg.any? ? gen_cfg : nil
-      end
-
       # Build parts array for Gemini API from formatted content
       # Converts VisionSupport format to Gemini's specific format
       # @param content [String, Array] Formatted content from VisionSupport

data/lib/llm_conductor/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LlmConductor
-  VERSION = '1.8.2'
+  VERSION = '1.8.3'
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: llm_conductor
 version: !ruby/object:Gem::Version
-  version: 1.8.2
+  version: 1.8.3
 platform: ruby
 authors:
 - Ben Zheng
 bindir: exe
 cert_chain: []
-date: 2026-06-11 00:00:00.000000000 Z
+date: 2026-08-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -172,6 +172,7 @@ files:
 - docs/vision-support.md
 - examples/claude_vision_usage.rb
 - examples/data_builder_usage.rb
+- examples/gemini_thinking_usage.rb
 - examples/gemini_usage.rb
 - examples/gemini_vision_usage.rb
 - examples/gpt_vision_usage.rb
@@ -187,6 +188,7 @@ files:
 - lib/llm_conductor/client_factory.rb
 - lib/llm_conductor/clients/anthropic_client.rb
 - lib/llm_conductor/clients/base_client.rb
+- lib/llm_conductor/clients/concerns/gemini_generation_config.rb
 - lib/llm_conductor/clients/concerns/vision_support.rb
 - lib/llm_conductor/clients/gemini_client.rb
 - lib/llm_conductor/clients/gpt_client.rb