geminai 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 87a7d8da785e91c6871f9f108570fb01f3165530ec932629776b9e61e7bc994f
-  data.tar.gz: 90235d17777b4c869e5523171c8deeaf961b9727a9204f76caefe594f93ff24e
+  metadata.gz: 1e37b88649fe531aa20ebbc70d3c452f694c11d151c1faf97ba49960b3b7445a
+  data.tar.gz: 3bf4c91537790276633c98ce1a8ca92a94d3cb44560e9708beef85e02f052066
 SHA512:
-  metadata.gz: 3baba4a0640a4e1d30300e502b01bf2edfa1797230c39c72615b706b107eb1f22d4018b7a15ad766c85b6bce852e92beaa84cd2df43d577a05c5791cf6704fb3
-  data.tar.gz: f0659f0c2a44b6b6115b7114020c82b72560ce0882382a5bb6b8ad5efc2f2229ff2f26b4f183bcb06827411f859771f270d91ff330214cfc8fe280f9b7d4b26f
+  metadata.gz: 789cc18e017f30e17df21c17d7c36507f935948a5537c89a268e96889a1029259a3e96acdddfe8dacb2c24780ac8958563a592fa90145fb32c859e9b562510b1
+  data.tar.gz: 1a6510f4c084578c2d77a40432d179d7fe23a508f3698d53634001b7dab2805e5821d9b1283cda55bc9b9d478bdbc10c537a099293a0a582428d5ce333e04c46

data/README.md

@@ -11,10 +11,35 @@ gem 'geminai'
 
 ## Setup
 
+### Option 1: Global Configuration (Recommended for Rails initializers)
+
+You can configure the client settings globally (e.g. in `config/initializers/geminai.rb`):
+
+```ruby
+require 'geminai'
+
+Geminai.configure do |config|
+  config.api_key = ENV['GEMINI_API_KEY']
+  # config.base_url = "https://generativelanguage.googleapis.com" # Optional, default value
+end
+```
+
+Once configured globally, you can instantiate the client without passing arguments:
+
+```ruby
+ai = Geminai.new
+```
+
+### Option 2: Direct Instantiation
+
+Alternatively, you can instantiate the client by passing the API key directly:
+
 ```ruby
 require 'geminai'
 
 ai = Geminai.new(ENV['GEMINI_API_KEY'])
+# or with a custom base url:
+ai = Geminai.new('YOUR_API_KEY', base_url: 'https://custom-url.com')
 ```
 
 ---
@@ -31,7 +56,7 @@ prompt = "what is the latest news on alphabet's stock price?"
 interaction = client.interact(
   model: 'gemini-3.5-flash',
   input: prompt,
-  tools: [{ type: 'google_search' }],
+  tools: [:google_search],
   store: false # Operate statelessly
 )
 
@@ -122,6 +147,48 @@ edit_interaction = client.interact(
 )
 ```
 
+### 5. Structured JSON Output (JSON Schema)
+
+Geminai supports structured JSON output using JSON schemas. You can pass a schema layout to define target properties, types, and constraints for the model output:
+
+```ruby
+schema = {
+  name: :string,
+  price: :number,
+  url: :string
+}
+
+interaction = client.interact(
+  model: 'gemini-3.5-flash',
+  input: 'Recommend a good mechanical keyboard with its name, estimated price in USD, and a manufacturer URL.',
+  schema: schema,
+  store: false
+)
+
+# The output text is guaranteed to be a JSON string adhering to the schema
+puts interaction.output_text
+# => "{\"name\":\"Keychron K2\",\"price\":79.99,\"url\":\"https://www.keychron.com/\"}"
+
+# You can also request a top-level list/array by wrapping the schema in a Ruby Array:
+array_schema = [
+  {
+    name: :string,
+    price: :number,
+    url: :string
+  }
+]
+
+array_interaction = client.interact(
+  model: 'gemini-3.5-flash',
+  input: 'Recommend three good mechanical keyboards.',
+  schema: array_schema,
+  store: false
+)
+
+puts array_interaction.output_text
+# => "[{\"name\":\"Keychron K2\",\"price\":79.99,\"url\":\"https://www.keychron.com/\"}, ...]"
+```
+
 ## Running Tests
 
 To run the integration tests (which execute live requests to the API), verify your `GEMINI_API_KEY` is present in your environment and run:

data/lib/geminai/client.rb

@@ -7,8 +7,8 @@ module Geminai
     attr_reader :api_key, :base_url
 
     def initialize(api_key: nil, base_url: nil)
-      @api_key = api_key || ENV["GEMINI_API_KEY"]
-      @base_url = base_url || "https://generativelanguage.googleapis.com"
+      @api_key = api_key || Geminai.configuration.api_key
+      @base_url = base_url || Geminai.configuration.base_url
 
       if @api_key.nil? || @api_key.empty?
         raise ArgumentError, "API Key is required"
@@ -56,6 +56,17 @@ module Geminai
         body[:generation_config] = {speech_config: [{voice: voice}]}
       end
 
+      # Handle tools normalization if present
+      if options.key?(:tools)
+        options[:tools] = Array(options[:tools]).map do |tool|
+          if tool.is_a?(Symbol) || tool.is_a?(String)
+            {type: tool.to_s}
+          else
+            tool
+          end
+        end
+      end
+
       # Merge other options, allowing them to override shortcuts if explicitly provided
       options.each do |k, v|
         if body[k].is_a?(Hash) && v.is_a?(Hash)

data/lib/geminai/configuration.rb

@@ -0,0 +1,10 @@
+module Geminai
+  class Configuration
+    attr_accessor :api_key, :base_url
+
+    def initialize
+      @api_key = ENV["GEMINI_API_KEY"]
+      @base_url = "https://generativelanguage.googleapis.com"
+    end
+  end
+end

data/lib/geminai/version.rb

@@ -1,3 +1,3 @@
 module Geminai
-  VERSION = "1.1.0"
+  VERSION = "1.2.0"
 end

data/lib/geminai.rb

@@ -4,10 +4,23 @@ require_relative "geminai/grounding_metadata"
 require_relative "geminai/interaction"
 require_relative "geminai/client"
 require_relative "geminai/schema_builder"
+require_relative "geminai/configuration"
 
 module Geminai
+  class << self
+    attr_writer :configuration
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+  end
+
   # Helper to construct a client
-  def self.new(api_key, base_url: nil)
+  def self.new(api_key = nil, base_url: nil)
     Client.new(api_key: api_key, base_url: base_url)
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: geminai
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - swlkr
@@ -18,6 +18,7 @@ files:
 - README.md
 - lib/geminai.rb
 - lib/geminai/client.rb
+- lib/geminai/configuration.rb
 - lib/geminai/grounding_metadata.rb
 - lib/geminai/interaction.rb
 - lib/geminai/schema_builder.rb