geminai 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9d805349d2b5e83401e3d9e299d237210d3bc758985d42e5308b1302f8e436c6
+  data.tar.gz: '0887d0adca55f7ec97bc12932be5e523ab0859dce30ecbb0d42b99625ce2f121'
+SHA512:
+  metadata.gz: 1b9bc352fc5c5222b4ed7d2236e2a7299de81676344175d8d975384025d62705c10312013ee3874dc401e3204ba1006f20a0716be9fa48331bf74d8f5cace6db
+  data.tar.gz: 000f7985bf738b8dfb0f2f13f72260f8e179b78c6bdb12255309c6c80ed310003e3fa8367b0a0658db52eaba6f2541f20c85c9ea26751628f27167f81472f350

data/README.md

@@ -0,0 +1,115 @@
+# geminai
+
+A gem for gemini's interactions api
+
+* **Built-in Tools**: Native search grounding (`google_search`), mapping citations, and suggestions.
+* **Image Generation**: High-fidelity native image generation (`gemini-3.1-flash-image`) with direct config like `aspect_ratio` and `image_size`.
+* **Stateful Conversations**: Seamless multi-turn conversations managed server-side via `previous_interaction_id`.
+* **Stateless Conversations**: Client-managed conversation paths using `store: false`.
+* **Zero Dependencies**: Pure Ruby standard library (`net/http` and `json`)
+
+## Install
+
+```ruby
+# Gemfile
+gem 'geminai'
+```
+
+## Setup
+
+```ruby
+require 'geminai'
+
+ai = Geminai.new(ENV['GEMINI_API_KEY'])
+```
+
+---
+
+## Usage Examples
+
+### 1. Google Search
+
+Geminai enables Google Search by passing the `google_search` tool
+
+```ruby
+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' }],
+  store: false # Operate statelessly
+)
+
+# 1. Output the generation
+puts interaction.output_text
+
+# 2. Extract grounding metadata
+metadata = interaction.grounding_metadata
+
+puts "\nWeb Search Queries Run:"
+p metadata.web_search_queries
+# => ["Bloomberg", ...]
+
+puts "\nWeb Citations:"
+metadata.citations.each do |citation|
+  puts "- #{citation[:title]} @ #{citation[:url]} (indexes: #{citation[:start_index]}..#{citation[:end_index]})"
+end
+# => - bloomberge.com @ https://vertexaisearch.cloud.google.com/grounding-api-redirect/...
+```
+
+### 2. Image Generation
+
+Geminai includes a helper method `generate_image` which calls the Interactions API specifying `type: "image"` under `response_format`.
+
+```ruby
+require 'base64'
+
+interaction = client.generate_image(
+  "An image of a pelican riding a bicycle",
+  model: 'gemini-3.1-flash-image',
+  aspect_ratio: '1:1',
+  image_size: '1K',
+  store: false
+)
+
+# Extract and save generated images
+interaction.output_images.each_with_index do |img, index|
+  File.binwrite("pelican#{index}.png", Base64.decode64(img[:data]))
+  puts "Saved pelican_#{index}.png"
+end
+```
+
+### 3. Multi-turn Stateful Conversations
+
+The Interactions API handles conversation history server-side. To continue a thread, pass `store: true` on your turns and feed the `id` of the previous interaction back into your subsequent requests using `previous_interaction_id`.
+
+```ruby
+# Turn 1: Save the context on the server
+interaction_1 = client.interact(
+  model: 'gemini-3.5-flash',
+  input: 'My favorite jihad is a butlerian jihad',
+  store: true
+)
+
+# Turn 2: Query context referencing the first interaction ID
+interaction_2 = client.interact(
+  model: 'gemini-3.5-flash',
+  input: 'What is my favorite jihad?',
+  previous_interaction_id: interaction_1.id,
+  store: true
+)
+
+puts interaction_2.output_text
+# => "Your favorite jihad is a butlerian jihad."
+```
+
+---
+
+## 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:
+
+```bash
+ruby -Ilib test/geminai_test.rb
+```

data/lib/geminai/client.rb

@@ -0,0 +1,93 @@
+require "net/http"
+require "uri"
+require "json"
+
+module Geminai
+  class Client
+    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"
+
+      if @api_key.nil? || @api_key.empty?
+        raise ArgumentError, "API Key is required"
+      end
+    end
+
+    def interact(model:, input:, **options)
+      uri = URI.parse("#{@base_url}/v1beta/interactions")
+
+      body = {
+        model: model,
+        input: input
+      }
+
+      # Forward all recognized interactions API request parameters
+      [
+        :system_instruction,
+        :generation_config,
+        :response_format,
+        :tools,
+        :previous_interaction_id,
+        :stream,
+        :store
+      ].each do |opt|
+        body[opt] = options[opt] if options.key?(opt)
+      end
+
+      # Handle any extra keys passed in options as well to be fully future-proof
+      options.each do |k, v|
+        next if body.key?(k)
+        body[k] = v
+      end
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = (uri.scheme == "https")
+
+      # Net::HTTP defaults read timeout is 60s, but search grounding or image generation can take longer,
+      # let's set a generous timeout.
+      http.read_timeout = 120
+
+      request = Net::HTTP::Post.new(uri.request_uri)
+      request["Content-Type"] = "application/json"
+      request["x-goog-api-key"] = @api_key
+      request.body = JSON.generate(body)
+
+      response = http.request(request)
+
+      unless response.code == "200"
+        raise(
+          ApiError.new("API Request failed with code #{response.code}: #{response.body}", response.code, response.body)
+        )
+      end
+
+      data = JSON.parse(response.body, symbolize_names: true)
+      Interaction.new(data)
+    end
+
+    # Helper method for image generation using response_format
+    def generate_image(prompt, model:, aspect_ratio: "1:1", image_size: "1K", **options)
+      interact(
+        model: model,
+        input: prompt,
+        response_format: {
+          type: "image",
+          aspect_ratio: aspect_ratio,
+          image_size: image_size
+        },
+        **options
+      )
+    end
+  end
+
+  class ApiError < StandardError
+    attr_reader :code, :response_body
+
+    def initialize(message, code = nil, response_body = nil)
+      super(message)
+      @code = code
+      @response_body = response_body
+    end
+  end
+end

data/lib/geminai/grounding_metadata.rb

@@ -0,0 +1,15 @@
+module Geminai
+  class GroundingMetadata
+    attr_reader :web_search_queries, :citations, :search_suggestions
+
+    def initialize(web_search_queries: [], citations: [], search_suggestions: nil)
+      @web_search_queries = web_search_queries
+      @citations = citations
+      @search_suggestions = search_suggestions
+    end
+
+    def empty?
+      @web_search_queries.empty? && @citations.empty? && @search_suggestions.nil?
+    end
+  end
+end

data/lib/geminai/interaction.rb

@@ -0,0 +1,97 @@
+module Geminai
+  class Interaction
+    attr_reader :id, :status, :usage, :created, :updated, :model, :steps, :raw_data
+
+    def initialize(data)
+      @raw_data = data
+      @id = data[:id]
+      @status = data[:status]
+      @usage = data[:usage]
+      @created = data[:created]
+      @updated = data[:updated]
+      @model = data[:model]
+
+      @steps = (data[:steps] || []).map { |step_data| Step.new(step_data) }
+    end
+
+    def output_text
+      text_parts = []
+      @steps.each do |step|
+        next unless step.model_output?
+        (step.content || []).each do |part|
+          text_parts << part[:text] if part[:type] == "text" && part[:text]
+        end
+      end
+
+      text_parts.join("")
+    end
+
+    def output_images
+      images = []
+      @steps.each do |step|
+        next unless step.model_output?
+        (step.content || []).each do |part|
+          if part[:type] == "image"
+            images <<
+              {
+                data: part[:data],
+                mime_type: part[:mime_type]
+              }
+          elsif part[:image]
+            # Handle other possible image shapes in responses if applicable
+            images <<
+              {
+                data: part[:image][:data] || part[:image][:image_bytes],
+                mime_type: part[:image][:mime_type]
+              }
+          end
+        end
+      end
+
+      images
+    end
+
+    def grounding_metadata
+      queries = []
+      citations = []
+      suggestions = nil
+
+      @steps.each do |step|
+        if step.google_search_call?
+          if step.arguments && step.arguments[:queries]
+            queries.concat(step.arguments[:queries])
+          end
+        elsif step.google_search_result?
+          if step.result
+            (step.result || []).each do |res|
+              if res[:search_suggestions]
+                suggestions = res[:search_suggestions]
+              end
+            end
+          end
+        elsif step.model_output?
+          (step.content || []).each do |part|
+            if part[:type] == "text" && part[:annotations]
+              part[:annotations].each do |ann|
+                citations <<
+                  {
+                    start_index: ann[:start_index],
+                    end_index: ann[:end_index],
+                    url: ann[:url],
+                    title: ann[:title],
+                    type: ann[:type]
+                  }
+              end
+            end
+          end
+        end
+      end
+
+      GroundingMetadata.new(
+        web_search_queries: queries.uniq,
+        citations: citations,
+        search_suggestions: suggestions
+      )
+    end
+  end
+end

data/lib/geminai/step.rb

@@ -0,0 +1,31 @@
+module Geminai
+  class Step
+    attr_reader :id, :type, :signature, :content, :arguments, :result, :raw_step
+
+    def initialize(data)
+      @raw_step = data
+      @id = data[:id]
+      @type = data[:type]
+      @signature = data[:signature]
+      @content = data[:content]
+      @arguments = data[:arguments]
+      @result = data[:result]
+    end
+
+    def thought?
+      @type == "thought"
+    end
+
+    def model_output?
+      @type == "model_output"
+    end
+
+    def google_search_call?
+      @type == "google_search_call"
+    end
+
+    def google_search_result?
+      @type == "google_search_result"
+    end
+  end
+end

data/lib/geminai/version.rb

@@ -0,0 +1,3 @@
+module Geminai
+  VERSION = "0.1.0"
+end

data/lib/geminai.rb

@@ -0,0 +1,12 @@
+require_relative "geminai/version"
+require_relative "geminai/step"
+require_relative "geminai/grounding_metadata"
+require_relative "geminai/interaction"
+require_relative "geminai/client"
+
+module Geminai
+  # Helper to construct a client
+  def self.new(api_key, base_url: nil)
+    Client.new(api_key: api_key, base_url: base_url)
+  end
+end

metadata

@@ -0,0 +1,48 @@
+--- !ruby/object:Gem::Specification
+name: geminai
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- swlkr
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: A gem for google's gemini interactions api
+email: []
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/geminai.rb
+- lib/geminai/client.rb
+- lib/geminai/grounding_metadata.rb
+- lib/geminai/interaction.rb
+- lib/geminai/step.rb
+- lib/geminai/version.rb
+homepage: https://github.com/swlkr/geminai
+licenses:
+- 0BSD
+metadata:
+  homepage_uri: https://github.com/swlkr/geminai
+  source_code_uri: https://github.com/swlkr/geminai
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.2
+specification_version: 4
+summary: Use google's gemini interactions api
+test_files: []