riffer 0.21.0 → 0.23.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8975a79d79a073d1bca29cd43216049766975f010b74dbc6ba1dbaaf22f69982
-  data.tar.gz: 5473e7c42541581bf7ad3c2efd046a3f3e76201e8b0c1a9a5ef324cc8175ae47
+  metadata.gz: 6c8de18bc9f5531012f3ccbf37098925f0f58a446b1ee528cc2bb60a13ef5989
+  data.tar.gz: 32343e215229cb1a02f19ffe61d5d0f128654f2d4bf128b2a23e7ef67908b0aa
 SHA512:
-  metadata.gz: a331b45d49617ffaa73b65df988d2b018fcc214c25480880bb9b420ac3415a5abf5a4703e2e1568d3982c7bebad77a3710b8d1f04a83b0f063117e35298bc485
-  data.tar.gz: 3ed3b7446ce0385cf0a70a795ac7c00c27dc786a815b66bf77fe3927e4cb9bbae806342835eeb0759a5b7dcf8eb3b04df8fad249a69040e8b7a48a88da7435fe
+  metadata.gz: 7f8f6bdbe623eabacc481f8264f9d43472c1d152d2383736087102db93e6d55047506d2fd6e7ec63e6647ad03aafb6f08861fcfed5ae6e44d54acd1a722041f1
+  data.tar.gz: 2ca5412c0f1c6a4f86e53f7d53495dcf8073e85d6173a92e0dd58a40c111cd2ed1e7f658d92f1d1bbdcd194bbf8c5bc17d00fa890dfc9186ec86885baacf5991

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.21.0"
+  ".": "0.23.0"
 }

data/CHANGELOG.md

@@ -5,6 +5,29 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.23.0](https://github.com/janeapp/riffer/compare/riffer/v0.22.0...riffer/v0.23.0) (2026-04-15)
+
+
+### Features
+
+* add Gemini provider ([#199](https://github.com/janeapp/riffer/issues/199)) ([d0f0823](https://github.com/janeapp/riffer/commit/d0f08237052258be64a8fb63e0d1c23508258176))
+
+## [0.22.0](https://github.com/janeapp/riffer/compare/riffer/v0.21.0...riffer/v0.22.0) (2026-04-09)
+
+
+### ⚠ BREAKING CHANGES
+
+* `Tool.name` returns `namespace/tool_name` instead of `namespace__tool_name`.
+
+### Features
+
+* use human-friendly `/` separator for tool names ([#202](https://github.com/janeapp/riffer/issues/202)) ([8dda251](https://github.com/janeapp/riffer/commit/8dda251ff6d91a6cebbbb82082b7ac21c2a51253))
+
+
+### Bug Fixes
+
+* release 0.22.0 ([#204](https://github.com/janeapp/riffer/issues/204)) ([860a500](https://github.com/janeapp/riffer/commit/860a500bb6e991de8018b43cda0c5f2662e22402))
+
 ## [0.21.0](https://github.com/janeapp/riffer/compare/riffer/v0.20.0...riffer/v0.21.0) (2026-04-09)
 
 

data/docs/providers/01_PROVIDERS.md

@@ -10,6 +10,7 @@ Providers are adapters that connect Riffer to LLM services. They implement a com
 | Azure OpenAI   | `azure_openai`   | `openai`                 |
 | Amazon Bedrock | `amazon_bedrock` | `aws-sdk-bedrockruntime` |
 | Anthropic      | `anthropic`      | `anthropic`              |
+| Gemini         | `gemini`         | None                     |
 | Mock           | `mock`           | None                     |
 
 ## Model String Format
@@ -22,6 +23,7 @@ class MyAgent < Riffer::Agent
   model 'azure_openai/gpt-5-mini'                                     # Azure OpenAI
   model 'amazon_bedrock/us.anthropic.claude-haiku-4-5-20251001-v1:0'  # Bedrock
   model 'anthropic/claude-haiku-4-5-20251001'                         # Anthropic
+  model 'gemini/gemini-2.5-flash-lite'                                # Gemini
   model 'mock/any'                                                    # Mock provider
 end
 ```
@@ -160,6 +162,9 @@ Riffer::Providers::Repository.find(:amazon_bedrock)
 Riffer::Providers::Repository.find(:anthropic)
 # => Riffer::Providers::Anthropic
 
+Riffer::Providers::Repository.find(:gemini)
+# => Riffer::Providers::Gemini
+
 Riffer::Providers::Repository.find(:mock)
 # => Riffer::Providers::Mock
 ```
@@ -172,3 +177,4 @@ Riffer::Providers::Repository.find(:mock)
 - [Azure OpenAI](05_AZURE_OPENAI.md) - GPT models via Azure
 - [Mock](06_MOCK_PROVIDER.md) - Mock provider for testing
 - [Custom Providers](07_CUSTOM_PROVIDERS.md) - Creating your own provider
+- [Gemini](08_GEMINI.md) - Gemini models via Google GenAI API

data/docs/providers/08_GEMINI.md

@@ -0,0 +1,142 @@
+# Gemini Provider
+
+The Gemini provider connects to Google's Gemini models via the Gemini REST API.
+
+## Configuration
+
+Configure your Gemini API key:
+
+```ruby
+Riffer.configure do |config|
+  config.gemini.api_key = ENV['GEMINI_API_KEY']
+end
+```
+
+Or per-agent:
+
+```ruby
+class MyAgent < Riffer::Agent
+  model 'gemini/gemini-2.5-flash-lite'
+  provider_options api_key: ENV['GEMINI_API_KEY']
+end
+```
+
+## Supported Models
+
+Use Gemini model IDs in the `gemini/model` format:
+
+```ruby
+model 'gemini/gemini-2.5-flash-lite'
+model 'gemini/gemini-2.5-pro'
+model 'gemini/gemini-2.5-flash'
+```
+
+## Model Options
+
+### temperature
+
+Controls randomness:
+
+```ruby
+model_options temperature: 0.7
+```
+
+### maxOutputTokens
+
+Maximum tokens in response:
+
+```ruby
+model_options maxOutputTokens: 4096
+```
+
+### topP
+
+Nucleus sampling:
+
+```ruby
+model_options topP: 0.9
+```
+
+## Usage
+
+### Basic Generation
+
+```ruby
+provider = Riffer::Providers::Gemini.new(api_key: ENV['GEMINI_API_KEY'])
+
+response = provider.generate_text(
+  prompt: "Hello!",
+  model: "gemini-2.5-flash-lite"
+)
+puts response.content
+```
+
+### Streaming
+
+```ruby
+provider.stream_text(prompt: "Tell me a story", model: "gemini-2.5-flash-lite").each do |event|
+  case event
+  when Riffer::StreamEvents::TextDelta
+    print event.content
+  when Riffer::StreamEvents::TextDone
+    puts "\n---"
+  end
+end
+```
+
+### Structured Output
+
+```ruby
+params = Riffer::Params.new
+params.required(:sentiment, String)
+params.required(:score, Float)
+structured_output = Riffer::StructuredOutput.new(params)
+
+response = provider.generate_text(
+  prompt: "Analyze: 'This is great!'",
+  model: "gemini-2.5-flash-lite",
+  structured_output: structured_output
+)
+puts response.structured_output
+```
+
+### Tool Calling
+
+```ruby
+class WeatherTool < Riffer::Tool
+  description "Gets weather"
+  params do
+    required :city, String
+  end
+  def call(context:, city:)
+    text("Sunny in #{city}")
+  end
+end
+
+response = provider.generate_text(
+  prompt: "What's the weather in Tokyo?",
+  model: "gemini-2.5-flash-lite",
+  tools: [WeatherTool]
+)
+```
+
+### File Support
+
+Gemini supports inline base64-encoded files (images and documents):
+
+```ruby
+file = Riffer::FilePart.new(data: base64_data, media_type: "image/png")
+response = provider.generate_text(
+  prompt: "Describe this image",
+  model: "gemini-2.5-flash-lite",
+  files: [file]
+)
+```
+
+**Note:** URL-based file references are not supported. Provide base64-encoded data instead.
+
+## Limitations
+
+- **No web search** - Gemini's standard API does not include a web search tool
+- **No URL files** - Only base64 inline data is supported for file attachments
+- **Tool call IDs** - Gemini does not return unique call IDs for tool invocations; IDs are generated client-side

data/lib/riffer/config.rb

@@ -18,6 +18,7 @@ class Riffer::Config
   AmazonBedrock = Struct.new(:api_token, :region, keyword_init: true)
   Anthropic = Struct.new(:api_key, keyword_init: true)
   AzureOpenAI = Struct.new(:api_key, :endpoint, keyword_init: true)
+  Gemini = Struct.new(:api_key, :open_timeout, :read_timeout, keyword_init: true)
   OpenAI = Struct.new(:api_key, keyword_init: true)
   Evals = Struct.new(:judge_model, keyword_init: true)
 
@@ -30,6 +31,9 @@ class Riffer::Config
   # Azure OpenAI configuration (Struct with +api_key+ and +endpoint+).
   attr_reader :azure_openai #: Riffer::Config::AzureOpenAI
 
+  # Google Gemini configuration (Struct with +api_key+, +open_timeout+, and +read_timeout+).
+  attr_reader :gemini #: Riffer::Config::Gemini
+
   # OpenAI configuration (Struct with +api_key+).
   attr_reader :openai #: Riffer::Config::OpenAI
 
@@ -61,6 +65,7 @@ class Riffer::Config
     @amazon_bedrock = AmazonBedrock.new
     @anthropic = Anthropic.new
     @azure_openai = AzureOpenAI.new
+    @gemini = Gemini.new
     @openai = OpenAI.new
     @evals = Evals.new
     @tool_runtime = Riffer::ToolRuntime::Inline.new

data/lib/riffer/providers/amazon_bedrock.rb

@@ -120,7 +120,7 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
       if block.respond_to?(:tool_use) && block.tool_use
         tool_calls << Riffer::Messages::Assistant::ToolCall.new(
           call_id: block.tool_use.tool_use_id,
-          name: block.tool_use.name,
+          name: decode_tool_name(block.tool_use.name, tools: @current_tools),
           arguments: block.tool_use.input.to_json
         )
       end
@@ -160,7 +160,7 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   def handle_content_block_start_tool_use(event, state:, yielder:)
     state[:tool_call] = {
       id: event.start.tool_use.tool_use_id,
-      name: event.start.tool_use.name,
+      name: decode_tool_name(event.start.tool_use.name, tools: @current_tools),
       arguments: ""
     }
   end
@@ -258,7 +258,7 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
       content << {
         tool_use: {
           tool_use_id: tc.call_id,
-          name: tc.name,
+          name: encode_tool_name(tc.name),
           input: parse_tool_arguments(tc.arguments)
         }
       }
@@ -327,7 +327,7 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   def convert_tool_to_bedrock_format(tool)
     {
       tool_spec: {
-        name: tool.name,
+        name: encode_tool_name(tool.name),
         description: tool.description,
         input_schema: {
           json: tool.parameters_schema(strict: true)

data/lib/riffer/providers/anthropic.rb

@@ -123,7 +123,7 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
       if block.type.to_s == "tool_use"
         tool_calls << Riffer::Messages::Assistant::ToolCall.new(
           call_id: block.id,
-          name: block.name,
+          name: decode_tool_name(block.name, tools: @current_tools),
           arguments: block.input.to_json
         )
       end
@@ -229,7 +229,7 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
     yielder << Riffer::StreamEvents::ToolCallDone.new(
       item_id: content_block.id,
       call_id: content_block.id,
-      name: content_block.name,
+      name: decode_tool_name(content_block.name, tools: @current_tools),
       arguments: arguments
     )
     state[:tool_call] = nil
@@ -339,7 +339,7 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
       content << {
         type: "tool_use",
         id: tc.call_id,
-        name: tc.name,
+        name: encode_tool_name(tc.name),
         input: parse_tool_arguments(tc.arguments)
       }
     end
@@ -365,7 +365,7 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
   #: (singleton(Riffer::Tool)) -> Hash[Symbol, untyped]
   def convert_tool_to_anthropic_format(tool)
     {
-      name: tool.name,
+      name: encode_tool_name(tool.name),
       description: tool.description,
       input_schema: tool.parameters_schema(strict: true)
     }

data/lib/riffer/providers/base.rb

@@ -20,6 +20,8 @@ class Riffer::Providers::Base
   include Riffer::Helpers::Dependencies
   include Riffer::Messages::Converter
 
+  WIRE_SEPARATOR = "__" #: String
+
   # Returns the preferred skill adapter for this provider.
   #
   # Override in subclasses for provider-specific formats.
@@ -36,6 +38,7 @@ class Riffer::Providers::Base
   #: (?prompt: String?, ?system: String?, ?messages: Array[Hash[Symbol, untyped] | Riffer::Messages::Base]?, ?model: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::FilePart]?, **untyped) -> Riffer::Messages::Assistant
   def generate_text(prompt: nil, system: nil, messages: nil, model: nil, files: nil, **options)
     validate_input!(prompt: prompt, system: system, messages: messages)
+    @current_tools = options[:tools] || []
     messages = normalize_messages(prompt: prompt, system: system, messages: messages, files: files)
     validate_normalized_messages!(messages)
     messages = merge_consecutive_messages(messages)
@@ -61,6 +64,7 @@ class Riffer::Providers::Base
   #: (?prompt: String?, ?system: String?, ?messages: Array[Hash[Symbol, untyped] | Riffer::Messages::Base]?, ?model: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::FilePart]?, **untyped) -> Enumerator[Riffer::StreamEvents::Base, void]
   def stream_text(prompt: nil, system: nil, messages: nil, model: nil, files: nil, **options)
     validate_input!(prompt: prompt, system: system, messages: messages)
+    @current_tools = options[:tools] || []
     messages = normalize_messages(prompt: prompt, system: system, messages: messages, files: files)
     validate_normalized_messages!(messages)
     messages = merge_consecutive_messages(messages)
@@ -72,6 +76,19 @@ class Riffer::Providers::Base
 
   private
 
+  #--
+  #: (String) -> String
+  def encode_tool_name(name)
+    name.gsub("/", WIRE_SEPARATOR)
+  end
+
+  #--
+  #: (String, tools: Array[Riffer::Tool]) -> String
+  def decode_tool_name(wire_name, tools:)
+    tool = tools.find { |t| encode_tool_name(t.name) == wire_name }
+    tool ? tool.name : wire_name
+  end
+
   #--
   #: (Array[Riffer::Messages::Base], String?, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
   def build_request_params(messages, model, options)

data/lib/riffer/providers/gemini.rb

@@ -0,0 +1,323 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require "json"
+require "net/http"
+require "securerandom"
+require "uri"
+
+# Google Gemini provider for Gemini models via the Gemini REST API.
+class Riffer::Providers::Gemini < Riffer::Providers::Base
+  BASE_URI = URI("https://generativelanguage.googleapis.com") #: URI::Generic
+  VALID_MODEL_PATTERN = /\A[a-zA-Z0-9._-]+\z/ #: Regexp
+  DEFAULT_OPEN_TIMEOUT = 10 #: Integer
+  DEFAULT_READ_TIMEOUT = 60 #: Integer
+
+  # Initializes the Gemini provider.
+  #
+  #--
+  #: (?api_key: String?, ?open_timeout: Integer?, ?read_timeout: Integer?, **untyped) -> void
+  def initialize(api_key: nil, open_timeout: nil, read_timeout: nil, **options)
+    api_key ||= Riffer.config.gemini.api_key
+    @api_key = api_key
+    @open_timeout = open_timeout || Riffer.config.gemini.open_timeout || DEFAULT_OPEN_TIMEOUT
+    @read_timeout = read_timeout || Riffer.config.gemini.read_timeout || DEFAULT_READ_TIMEOUT
+  end
+
+  private
+
+  #--
+  #: (Array[Riffer::Messages::Base], String?, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
+  def build_request_params(messages, model, options)
+    partitioned = partition_messages(messages)
+    tools = options[:tools]
+    structured_output = options[:structured_output]
+
+    params = {
+      model: model,
+      contents: partitioned[:contents]
+    }
+
+    params[:systemInstruction] = partitioned[:system_instruction] if partitioned[:system_instruction]
+
+    if tools && !tools.empty?
+      params[:tools] = [{
+        functionDeclarations: tools.map { |t| convert_tool_to_gemini_format(t) }
+      }]
+    end
+
+    generation_config = options.except(:tools, :structured_output)
+
+    if structured_output
+      generation_config[:responseMimeType] = "application/json"
+      generation_config[:responseSchema] = strip_additional_properties(structured_output.json_schema)
+    end
+
+    params[:generationConfig] = generation_config unless generation_config.empty?
+
+    params
+  end
+
+  #--
+  #: (Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
+  def execute_generate(params)
+    model = params[:model]
+    body = params.except(:model)
+    response = post_request(api_path(model, "generateContent"), body)
+    handle_api_error!(response) unless response.is_a?(Net::HTTPSuccess)
+    JSON.parse(response.body, symbolize_names: true)
+  end
+
+  #--
+  #: (Hash[Symbol, untyped]) -> String
+  def extract_content(response)
+    parts = response.dig(:candidates, 0, :content, :parts)
+    return "" unless parts
+
+    parts.filter_map { |part| part[:text] }.join
+  end
+
+  #--
+  #: (Hash[Symbol, untyped]) -> Array[Riffer::Messages::Assistant::ToolCall]
+  def extract_tool_calls(response)
+    parts = response.dig(:candidates, 0, :content, :parts)
+    return [] unless parts
+
+    parts.filter_map do |part|
+      next unless part[:functionCall]
+
+      fc = part[:functionCall]
+      Riffer::Messages::Assistant::ToolCall.new(
+        call_id: "gemini_call_#{SecureRandom.hex(12)}",
+        name: fc[:name],
+        arguments: encode_tool_arguments(fc[:args])
+      )
+    end
+  end
+
+  #--
+  #: (Hash[Symbol, untyped]) -> Riffer::TokenUsage?
+  def extract_token_usage(response)
+    usage = response[:usageMetadata]
+    return nil unless usage
+
+    Riffer::TokenUsage.new(
+      input_tokens: usage[:promptTokenCount] || 0,
+      output_tokens: usage[:candidatesTokenCount] || 0
+    )
+  end
+
+  #--
+  #: (Hash[Symbol, untyped], Enumerator::Yielder) -> void
+  def execute_stream(params, yielder)
+    model = params[:model]
+    body = params.except(:model)
+
+    uri = URI("#{BASE_URI}/#{api_path(model, "streamGenerateContent")}?alt=sse")
+    request = Net::HTTP::Post.new(uri)
+    request["Content-Type"] = "application/json"
+    request["x-goog-api-key"] = @api_key
+    request.body = body.to_json
+
+    full_text = +""
+    buffer = +""
+
+    process_chunk = lambda do |chunk|
+      buffer << chunk
+
+      while (match = buffer.match(/\r?\n\r?\n/))
+        frame = buffer.slice!(0, match.end(0)).strip
+        next unless frame.start_with?("data: ")
+
+        json_str = frame.delete_prefix("data: ").strip
+        next if json_str.empty?
+
+        parsed = JSON.parse(json_str, symbolize_names: true)
+        parts = parsed.dig(:candidates, 0, :content, :parts)
+
+        parts&.each do |part|
+          if part[:text]
+            full_text << part[:text]
+            yielder << Riffer::StreamEvents::TextDelta.new(part[:text])
+          elsif part[:functionCall]
+            fc = part[:functionCall]
+            call_id = "gemini_call_#{SecureRandom.hex(12)}"
+            arguments = encode_tool_arguments(fc[:args])
+            yielder << Riffer::StreamEvents::ToolCallDone.new(
+              item_id: call_id,
+              call_id: call_id,
+              name: fc[:name],
+              arguments: arguments
+            )
+          end
+        end
+
+        usage = parsed[:usageMetadata]
+        if usage && usage[:candidatesTokenCount]
+          yielder << Riffer::StreamEvents::TokenUsageDone.new(
+            token_usage: Riffer::TokenUsage.new(
+              input_tokens: usage[:promptTokenCount] || 0,
+              output_tokens: usage[:candidatesTokenCount] || 0
+            )
+          )
+        end
+      end
+    end
+
+    Net::HTTP.start(uri.hostname, uri.port, use_ssl: true, open_timeout: @open_timeout, read_timeout: @read_timeout) do |http|
+      http.request(request) do |response|
+        handle_api_error!(response) unless response.is_a?(Net::HTTPSuccess)
+
+        begin
+          response.read_body { |chunk| process_chunk.call(chunk) }
+        rescue IOError
+          process_chunk.call(response.body)
+        end
+      end
+    end
+
+    yielder << Riffer::StreamEvents::TextDone.new(full_text) unless full_text.empty?
+  end
+
+  #--
+  #: (Array[Riffer::Messages::Base]) -> Hash[Symbol, untyped]
+  def partition_messages(messages)
+    system_parts = []
+    contents = []
+
+    messages.each do |message|
+      case message
+      when Riffer::Messages::System
+        system_parts << {text: message.content}
+      when Riffer::Messages::User
+        if message.files.empty?
+          contents << {role: "user", parts: [{text: message.content}]}
+        else
+          parts = [{text: message.content}]
+          message.files.each { |file| parts << convert_file_part_to_gemini_format(file) }
+          contents << {role: "user", parts: parts}
+        end
+      when Riffer::Messages::Assistant
+        contents << convert_assistant_to_gemini_format(message)
+      when Riffer::Messages::Tool
+        contents << {
+          role: "user",
+          parts: [{
+            functionResponse: {
+              name: message.name,
+              response: {result: message.content}
+            }
+          }]
+        }
+      end
+    end
+
+    result = {contents: contents}
+    result[:system_instruction] = {parts: system_parts} unless system_parts.empty?
+    result
+  end
+
+  #--
+  #: (Riffer::Messages::Assistant) -> Hash[Symbol, untyped]
+  def convert_assistant_to_gemini_format(message)
+    parts = []
+    parts << {text: message.content} if message.content && !message.content.empty?
+
+    message.tool_calls.each do |tc|
+      parts << {
+        functionCall: {
+          name: tc.name,
+          args: parse_tool_arguments(tc.arguments)
+        }
+      }
+    end
+
+    {role: "model", parts: parts}
+  end
+
+  #--
+  #: (Riffer::FilePart) -> Hash[Symbol, untyped]
+  def convert_file_part_to_gemini_format(file)
+    if file.url?
+      raise Riffer::ArgumentError,
+        "Gemini provider does not support URL-based file references. Provide base64-encoded data instead."
+    end
+
+    {inlineData: {mimeType: file.media_type, data: file.data}}
+  end
+
+  #--
+  #: (singleton(Riffer::Tool)) -> Hash[Symbol, untyped]
+  def convert_tool_to_gemini_format(tool)
+    {
+      name: tool.name,
+      description: tool.description,
+      parameters: strip_additional_properties(tool.parameters_schema)
+    }
+  end
+
+  #--
+  #: (untyped) -> String
+  def encode_tool_arguments(args)
+    return "{}" unless args
+
+    args.is_a?(String) ? args : args.to_json
+  end
+
+  #--
+  #: (String, Hash[Symbol, untyped]) -> Net::HTTPResponse
+  def post_request(path, body)
+    uri = URI("#{BASE_URI}/#{path}")
+    request = Net::HTTP::Post.new(uri)
+    request["Content-Type"] = "application/json"
+    request["x-goog-api-key"] = @api_key
+    request.body = body.to_json
+    Net::HTTP.start(uri.hostname, uri.port, use_ssl: true, open_timeout: @open_timeout, read_timeout: @read_timeout) { |http| http.request(request) }
+  end
+
+  #--
+  #: (String, String) -> String
+  def api_path(model, method)
+    validate_model!(model)
+    "v1beta/models/#{model}:#{method}"
+  end
+
+  #--
+  #: (String) -> void
+  def validate_model!(model)
+    return if model.match?(VALID_MODEL_PATTERN)
+
+    raise Riffer::ArgumentError, "Invalid model name: #{model.inspect}. Model must contain only alphanumeric characters, hyphens, dots, and underscores."
+  end
+
+  #--
+  #: (Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
+  def strip_additional_properties(schema)
+    schema = schema.dup
+    schema.delete(:additionalProperties)
+
+    if schema[:properties]
+      schema[:properties] = schema[:properties].transform_values do |prop|
+        strip_additional_properties(prop)
+      end
+    end
+
+    if schema[:items].is_a?(Hash)
+      schema[:items] = strip_additional_properties(schema[:items])
+    end
+
+    schema
+  end
+
+  #--
+  #: (Net::HTTPResponse) -> void
+  def handle_api_error!(response)
+    body = begin
+      JSON.parse(response.body, symbolize_names: true)
+    rescue JSON::ParserError
+      {message: response.body}
+    end
+    error_message = body.dig(:error, :message) || body[:message] || response.body
+    raise Riffer::Error, "Gemini API error (#{response.code}): #{error_message}"
+  end
+end

data/lib/riffer/providers/open_ai.rb

@@ -107,7 +107,7 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
       if item.type == :function_call
         tool_calls << Riffer::Messages::Assistant::ToolCall.new(
           call_id: item.call_id,
-          name: item.name,
+          name: decode_tool_name(item.name, tools: @current_tools),
           arguments: item.arguments
         )
       end
@@ -158,7 +158,7 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
   #: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
   def handle_output_item_added_function_call(event, state:, yielder:)
     state[:tool_info][event.item.id] = {
-      name: event.item.name,
+      name: decode_tool_name(event.item.name, tools: @current_tools),
       call_id: event.item.call_id
     }
   end
@@ -284,7 +284,7 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
         items << {
           type: "function_call",
           call_id: tc.call_id,
-          name: tc.name,
+          name: encode_tool_name(tc.name),
           arguments: tc.arguments.is_a?(String) ? tc.arguments : tc.arguments.to_json
         }
       end
@@ -311,7 +311,7 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
   def convert_tool_to_openai_format(tool)
     {
       type: "function",
-      name: tool.name,
+      name: encode_tool_name(tool.name),
       description: tool.description,
       parameters: tool.parameters_schema(strict: true),
       strict: true

data/lib/riffer/providers/repository.rb

@@ -8,6 +8,7 @@ class Riffer::Providers::Repository
     amazon_bedrock: -> { Riffer::Providers::AmazonBedrock },
     anthropic: -> { Riffer::Providers::Anthropic },
     azure_openai: -> { Riffer::Providers::AzureOpenAI },
+    gemini: -> { Riffer::Providers::Gemini },
     openai: -> { Riffer::Providers::OpenAI },
     mock: -> { Riffer::Providers::Mock }
   }.freeze #: Hash[Symbol, ^() -> singleton(Riffer::Providers::Base)]

data/lib/riffer/skills/backend.rb

@@ -12,6 +12,8 @@
 class Riffer::Skills::Backend
   SKILL_FILENAME = "SKILL.md" #: String
 
+  def initialize = nil
+
   # Returns frontmatter for all available skills.
   #
   # Called once at the start of generate/stream.

data/lib/riffer/tool.rb

@@ -24,71 +24,9 @@ require "timeout"
 #   end
 #
 class Riffer::Tool
-  DEFAULT_TIMEOUT = 10 #: Integer
+  extend Riffer::Toolable
 
-  # Some providers do not allow "/" in tool names, so we use "__" as separator.
-  TOOL_SEPARATOR = "__" #: String
-
-  extend Riffer::Helpers::ClassNameConverter
-
-  # Gets or sets the tool description.
-  #
-  #--
-  #: (?String?) -> String?
-  def self.description(value = nil)
-    return @description if value.nil?
-    @description = value.to_s
-  end
-
-  # Gets or sets the tool identifier/name.
-  #
-  #--
-  #: (?String?) -> String
-  def self.identifier(value = nil)
-    return @identifier || class_name_to_path(Module.instance_method(:name).bind_call(self), separator: TOOL_SEPARATOR) if value.nil?
-    @identifier = value.to_s
-  end
-
-  # Alias for identifier - used by providers.
-  #
-  #--
-  #: (?String?) -> String
-  def self.name(value = nil)
-    return identifier(value) unless value.nil?
-    identifier
-  end
-
-  # Gets or sets the tool timeout in seconds.
-  #
-  #--
-  #: (?(Integer | Float)?) -> (Integer | Float)
-  def self.timeout(value = nil)
-    return @timeout || DEFAULT_TIMEOUT if value.nil?
-    @timeout = value.to_f
-  end
-
-  # Defines parameters using the Params DSL.
-  #
-  #--
-  #: () ?{ () -> void } -> Riffer::Params?
-  def self.params(&block)
-    return @params_builder if block.nil?
-    @params_builder = Riffer::Params.new
-    @params_builder.instance_eval(&block)
-  end
-
-  # Returns the JSON Schema for the tool's parameters.
-  #
-  #--
-  #: (?strict: bool) -> Hash[Symbol, untyped]
-  def self.parameters_schema(strict: false)
-    @params_builder&.to_json_schema(strict: strict) || empty_schema
-  end
-
-  def self.empty_schema # :nodoc:
-    {type: "object", properties: {}, required: [], additionalProperties: false}
-  end
-  private_class_method :empty_schema
+  kind :tool
 
   # Executes the tool with the given arguments.
   #

data/lib/riffer/toolable.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Riffer::Toolable provides the shared class-level DSL for anything that can
+# present as a tool to an LLM — tools today, and subagents/workflows in the
+# future.
+#
+# Extend this module to make a class discoverable as a tool by LLM providers.
+# Provides identifier, description, params, timeout, and JSON schema
+# generation.
+#
+# Instance-level execution concerns (+call+, +call_with_validation+, etc.)
+# are NOT part of Toolable — those belong on Riffer::Tool.
+#
+#   class MyTool
+#     extend Riffer::Toolable
+#
+#     description "Does something useful"
+#
+#     params do
+#       required :input, String
+#     end
+#   end
+#
+module Riffer::Toolable
+  DEFAULT_TIMEOUT = 10 #: Integer
+
+  # Tracks all classes that extend Toolable.
+  #
+  #--
+  #: (Module) -> void
+  def self.extended(base)
+    base.extend Riffer::Helpers::ClassNameConverter
+    @extenders ||= []
+    @extenders << base
+  end
+
+  # Returns all classes that have extended Toolable.
+  #
+  #--
+  #: () -> Array[Module]
+  def self.all
+    @extenders || []
+  end
+
+  # Gets or sets the tool description.
+  #
+  #--
+  #: (?String?) -> String?
+  def description(value = nil)
+    return @description if value.nil?
+    @description = value.to_s
+  end
+
+  # Gets or sets the tool identifier/name.
+  #
+  #--
+  #: (?String?) -> String
+  def identifier(value = nil)
+    return @identifier || class_name_to_path(Module.instance_method(:name).bind_call(self)) if value.nil?
+    @identifier = value.to_s
+  end
+
+  # Alias for identifier — used by providers.
+  #
+  #--
+  #: (?String?) -> String
+  def name(value = nil)
+    return identifier(value) unless value.nil?
+    identifier
+  end
+
+  # Gets or sets the tool timeout in seconds.
+  #
+  #--
+  #: (?(Integer | Float)?) -> (Integer | Float)
+  def timeout(value = nil)
+    return @timeout || DEFAULT_TIMEOUT if value.nil?
+    @timeout = value.to_f
+  end
+
+  # Defines parameters using the Params DSL.
+  #
+  #--
+  #: () ?{ () -> void } -> Riffer::Params?
+  def params(&block)
+    return @params_builder if block.nil?
+    @params_builder = Riffer::Params.new
+    @params_builder.instance_eval(&block)
+  end
+
+  # Returns the JSON Schema for the tool's parameters.
+  #
+  #--
+  #: (?strict: bool) -> Hash[Symbol, untyped]
+  def parameters_schema(strict: false)
+    @params_builder&.to_json_schema(strict: strict) || empty_schema
+  end
+
+  # Returns the kind of toolable entity.
+  #
+  # Defaults to +:tool+. Extensible to +:agent+, +:workflow+, etc.
+  #
+  #--
+  #: (?Symbol?) -> Symbol
+  def kind(value = nil)
+    return @kind || :tool if value.nil?
+    @kind = value.to_sym
+  end
+
+  # Returns a provider-agnostic tool schema hash.
+  #
+  #--
+  #: (?strict: bool) -> Hash[Symbol, untyped]
+  def to_tool_schema(strict: false)
+    {
+      name: name,
+      description: description,
+      parameters_schema: parameters_schema(strict: strict)
+    }
+  end
+
+  # Validates that the minimum required metadata is present for LLM tool use.
+  #
+  # Raises Riffer::ArgumentError if validation fails.
+  #
+  #--
+  #: () -> true
+  def validate_as_tool!
+    raise Riffer::ArgumentError, "#{self} must define a description" if description.nil? || description.to_s.strip.empty?
+    raise Riffer::ArgumentError, "#{self} must have an identifier" if identifier.nil? || identifier.to_s.strip.empty?
+    true
+  end
+
+  private
+
+  def empty_schema # :nodoc:
+    {type: "object", properties: {}, required: [], additionalProperties: false}
+  end
+end

data/lib/riffer/version.rb

@@ -2,5 +2,5 @@
 # rbs_inline: enabled
 
 module Riffer
-  VERSION = "0.21.0" #: String
+  VERSION = "0.23.0" #: String
 end

data/sig/generated/riffer/config.rbs

@@ -38,6 +38,17 @@ class Riffer::Config
                 | ({ ?api_key: untyped, ?endpoint: untyped }) -> instance
   end
 
+  class Gemini < Struct[untyped]
+    attr_accessor api_key(): untyped
+
+    attr_accessor open_timeout(): untyped
+
+    attr_accessor read_timeout(): untyped
+
+    def self.new: (?api_key: untyped, ?open_timeout: untyped, ?read_timeout: untyped) -> instance
+                | ({ ?api_key: untyped, ?open_timeout: untyped, ?read_timeout: untyped }) -> instance
+  end
+
   class OpenAI < Struct[untyped]
     attr_accessor api_key(): untyped
 
@@ -61,6 +72,9 @@ class Riffer::Config
   # Azure OpenAI configuration (Struct with +api_key+ and +endpoint+).
   attr_reader azure_openai: Riffer::Config::AzureOpenAI
 
+  # Google Gemini configuration (Struct with +api_key+, +open_timeout+, and +read_timeout+).
+  attr_reader gemini: Riffer::Config::Gemini
+
   # OpenAI configuration (Struct with +api_key+).
   attr_reader openai: Riffer::Config::OpenAI
 

data/sig/generated/riffer/providers/base.rbs

@@ -18,6 +18,8 @@ class Riffer::Providers::Base
 
   include Riffer::Messages::Converter
 
+  WIRE_SEPARATOR: String
+
   # Returns the preferred skill adapter for this provider.
   #
   # Override in subclasses for provider-specific formats.
@@ -40,6 +42,14 @@ class Riffer::Providers::Base
 
   private
 
+  # --
+  # : (String) -> String
+  def encode_tool_name: (String) -> String
+
+  # --
+  # : (String, tools: Array[Riffer::Tool]) -> String
+  def decode_tool_name: (String, tools: Array[Riffer::Tool]) -> String
+
   # --
   # : (Array[Riffer::Messages::Base], String?, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
   def build_request_params: (Array[Riffer::Messages::Base], String?, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]

data/sig/generated/riffer/providers/gemini.rbs

@@ -0,0 +1,84 @@
+# Generated from lib/riffer/providers/gemini.rb with RBS::Inline
+
+# Google Gemini provider for Gemini models via the Gemini REST API.
+class Riffer::Providers::Gemini < Riffer::Providers::Base
+  BASE_URI: URI::Generic
+
+  VALID_MODEL_PATTERN: Regexp
+
+  DEFAULT_OPEN_TIMEOUT: Integer
+
+  DEFAULT_READ_TIMEOUT: Integer
+
+  # Initializes the Gemini provider.
+  #
+  # --
+  # : (?api_key: String?, ?open_timeout: Integer?, ?read_timeout: Integer?, **untyped) -> void
+  def initialize: (?api_key: String?, ?open_timeout: Integer?, ?read_timeout: Integer?, **untyped) -> void
+
+  private
+
+  # --
+  # : (Array[Riffer::Messages::Base], String?, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
+  def build_request_params: (Array[Riffer::Messages::Base], String?, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
+
+  # --
+  # : (Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
+  def execute_generate: (Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
+
+  # --
+  # : (Hash[Symbol, untyped]) -> String
+  def extract_content: (Hash[Symbol, untyped]) -> String
+
+  # --
+  # : (Hash[Symbol, untyped]) -> Array[Riffer::Messages::Assistant::ToolCall]
+  def extract_tool_calls: (Hash[Symbol, untyped]) -> Array[Riffer::Messages::Assistant::ToolCall]
+
+  # --
+  # : (Hash[Symbol, untyped]) -> Riffer::TokenUsage?
+  def extract_token_usage: (Hash[Symbol, untyped]) -> Riffer::TokenUsage?
+
+  # --
+  # : (Hash[Symbol, untyped], Enumerator::Yielder) -> void
+  def execute_stream: (Hash[Symbol, untyped], Enumerator::Yielder) -> void
+
+  # --
+  # : (Array[Riffer::Messages::Base]) -> Hash[Symbol, untyped]
+  def partition_messages: (Array[Riffer::Messages::Base]) -> Hash[Symbol, untyped]
+
+  # --
+  # : (Riffer::Messages::Assistant) -> Hash[Symbol, untyped]
+  def convert_assistant_to_gemini_format: (Riffer::Messages::Assistant) -> Hash[Symbol, untyped]
+
+  # --
+  # : (Riffer::FilePart) -> Hash[Symbol, untyped]
+  def convert_file_part_to_gemini_format: (Riffer::FilePart) -> Hash[Symbol, untyped]
+
+  # --
+  # : (singleton(Riffer::Tool)) -> Hash[Symbol, untyped]
+  def convert_tool_to_gemini_format: (singleton(Riffer::Tool)) -> Hash[Symbol, untyped]
+
+  # --
+  # : (untyped) -> String
+  def encode_tool_arguments: (untyped) -> String
+
+  # --
+  # : (String, Hash[Symbol, untyped]) -> Net::HTTPResponse
+  def post_request: (String, Hash[Symbol, untyped]) -> Net::HTTPResponse
+
+  # --
+  # : (String, String) -> String
+  def api_path: (String, String) -> String
+
+  # --
+  # : (String) -> void
+  def validate_model!: (String) -> void
+
+  # --
+  # : (Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
+  def strip_additional_properties: (Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
+
+  # --
+  # : (Net::HTTPResponse) -> void
+  def handle_api_error!: (Net::HTTPResponse) -> void
+end

data/sig/generated/riffer/skills/backend.rbs

@@ -11,6 +11,8 @@
 class Riffer::Skills::Backend
   SKILL_FILENAME: String
 
+  def initialize: () -> untyped
+
   # Returns frontmatter for all available skills.
   #
   # Called once at the start of generate/stream.

data/sig/generated/riffer/tool.rbs

@@ -20,50 +20,7 @@
 #     end
 #   end
 class Riffer::Tool
-  DEFAULT_TIMEOUT: Integer
-
-  # Some providers do not allow "/" in tool names, so we use "__" as separator.
-  TOOL_SEPARATOR: String
-
-  extend Riffer::Helpers::ClassNameConverter
-
-  # Gets or sets the tool description.
-  #
-  # --
-  # : (?String?) -> String?
-  def self.description: (?String?) -> String?
-
-  # Gets or sets the tool identifier/name.
-  #
-  # --
-  # : (?String?) -> String
-  def self.identifier: (?String?) -> String
-
-  # Alias for identifier - used by providers.
-  #
-  # --
-  # : (?String?) -> String
-  def self.name: (?String?) -> String
-
-  # Gets or sets the tool timeout in seconds.
-  #
-  # --
-  # : (?(Integer | Float)?) -> (Integer | Float)
-  def self.timeout: (?(Integer | Float)?) -> (Integer | Float)
-
-  # Defines parameters using the Params DSL.
-  #
-  # --
-  # : () ?{ () -> void } -> Riffer::Params?
-  def self.params: () ?{ () -> void } -> Riffer::Params?
-
-  # Returns the JSON Schema for the tool's parameters.
-  #
-  # --
-  # : (?strict: bool) -> Hash[Symbol, untyped]
-  def self.parameters_schema: (?strict: bool) -> Hash[Symbol, untyped]
-
-  def self.empty_schema: () -> untyped
+  extend Riffer::Toolable
 
   # Executes the tool with the given arguments.
   #

data/sig/generated/riffer/toolable.rbs

@@ -0,0 +1,99 @@
+# Generated from lib/riffer/toolable.rb with RBS::Inline
+
+# Riffer::Toolable provides the shared class-level DSL for anything that can
+# present as a tool to an LLM — tools today, and subagents/workflows in the
+# future.
+#
+# Extend this module to make a class discoverable as a tool by LLM providers.
+# Provides identifier, description, params, timeout, and JSON schema
+# generation.
+#
+# Instance-level execution concerns (+call+, +call_with_validation+, etc.)
+# are NOT part of Toolable — those belong on Riffer::Tool.
+#
+#   class MyTool
+#     extend Riffer::Toolable
+#
+#     description "Does something useful"
+#
+#     params do
+#       required :input, String
+#     end
+#   end
+module Riffer::Toolable
+  DEFAULT_TIMEOUT: Integer
+
+  # Tracks all classes that extend Toolable.
+  #
+  # --
+  # : (Module) -> void
+  def self.extended: (Module) -> void
+
+  # Returns all classes that have extended Toolable.
+  #
+  # --
+  # : () -> Array[Module]
+  def self.all: () -> Array[Module]
+
+  # Gets or sets the tool description.
+  #
+  # --
+  # : (?String?) -> String?
+  def description: (?String?) -> String?
+
+  # Gets or sets the tool identifier/name.
+  #
+  # --
+  # : (?String?) -> String
+  def identifier: (?String?) -> String
+
+  # Alias for identifier — used by providers.
+  #
+  # --
+  # : (?String?) -> String
+  def name: (?String?) -> String
+
+  # Gets or sets the tool timeout in seconds.
+  #
+  # --
+  # : (?(Integer | Float)?) -> (Integer | Float)
+  def timeout: (?(Integer | Float)?) -> (Integer | Float)
+
+  # Defines parameters using the Params DSL.
+  #
+  # --
+  # : () ?{ () -> void } -> Riffer::Params?
+  def params: () ?{ () -> void } -> Riffer::Params?
+
+  # Returns the JSON Schema for the tool's parameters.
+  #
+  # --
+  # : (?strict: bool) -> Hash[Symbol, untyped]
+  def parameters_schema: (?strict: bool) -> Hash[Symbol, untyped]
+
+  # Returns the kind of toolable entity.
+  #
+  # Defaults to +:tool+. Extensible to +:agent+, +:workflow+, etc.
+  #
+  # --
+  # : (?Symbol?) -> Symbol
+  def kind: (?Symbol?) -> Symbol
+
+  # Returns a provider-agnostic tool schema hash.
+  #
+  # --
+  # : (?strict: bool) -> Hash[Symbol, untyped]
+  def to_tool_schema: (?strict: bool) -> Hash[Symbol, untyped]
+
+  # Validates that the minimum required metadata is present for LLM tool use.
+  #
+  # Raises Riffer::ArgumentError if validation fails.
+  #
+  # --
+  # : () -> true
+  def validate_as_tool!: () -> true
+
+  private
+
+  def empty_schema: () -> untyped
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: riffer
 version: !ruby/object:Gem::Version
-  version: 0.21.0
+  version: 0.23.0
 platform: ruby
 authors:
 - Jake Bottrall
@@ -35,14 +35,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.28.0
+        version: 1.32.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.28.0
+        version: 1.32.0
 - !ruby/object:Gem::Dependency
   name: aws-sdk-bedrockruntime
   requirement: !ruby/object:Gem::Requirement
@@ -63,14 +63,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.57.0
+        version: 0.58.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.57.0
+        version: 0.58.0
 - !ruby/object:Gem::Dependency
   name: async
   requirement: !ruby/object:Gem::Requirement
@@ -254,6 +254,7 @@ files:
 - docs/providers/05_AZURE_OPENAI.md
 - docs/providers/06_MOCK_PROVIDER.md
 - docs/providers/07_CUSTOM_PROVIDERS.md
+- docs/providers/08_GEMINI.md
 - lib/riffer.rb
 - lib/riffer/agent.rb
 - lib/riffer/agent/response.rb
@@ -292,6 +293,7 @@ files:
 - lib/riffer/providers/anthropic.rb
 - lib/riffer/providers/azure_open_ai.rb
 - lib/riffer/providers/base.rb
+- lib/riffer/providers/gemini.rb
 - lib/riffer/providers/mock.rb
 - lib/riffer/providers/open_ai.rb
 - lib/riffer/providers/repository.rb
@@ -332,6 +334,7 @@ files:
 - lib/riffer/tool_runtime/fibers.rb
 - lib/riffer/tool_runtime/inline.rb
 - lib/riffer/tool_runtime/threaded.rb
+- lib/riffer/toolable.rb
 - lib/riffer/tools.rb
 - lib/riffer/tools/response.rb
 - lib/riffer/version.rb
@@ -373,6 +376,7 @@ files:
 - sig/generated/riffer/providers/anthropic.rbs
 - sig/generated/riffer/providers/azure_open_ai.rbs
 - sig/generated/riffer/providers/base.rbs
+- sig/generated/riffer/providers/gemini.rbs
 - sig/generated/riffer/providers/mock.rbs
 - sig/generated/riffer/providers/open_ai.rbs
 - sig/generated/riffer/providers/repository.rbs
@@ -413,6 +417,7 @@ files:
 - sig/generated/riffer/tool_runtime/fibers.rbs
 - sig/generated/riffer/tool_runtime/inline.rbs
 - sig/generated/riffer/tool_runtime/threaded.rbs
+- sig/generated/riffer/toolable.rbs
 - sig/generated/riffer/tools.rbs
 - sig/generated/riffer/tools/response.rbs
 - sig/generated/riffer/version.rbs