riffer 0.22.0 → 0.23.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e6c1902fc4a3a1ad047491befa79ae44aa7aea3e160dda3303fe18c3670e477
-  data.tar.gz: d4407ecd6a3af8900e7a2a456870e5e4a4211df016259980bf8f5b559ad8df2f
+  metadata.gz: 6c8de18bc9f5531012f3ccbf37098925f0f58a446b1ee528cc2bb60a13ef5989
+  data.tar.gz: 32343e215229cb1a02f19ffe61d5d0f128654f2d4bf128b2a23e7ef67908b0aa
 SHA512:
-  metadata.gz: 5845e5336564993a8e23ff6a5a1c903fb28925991443d4beb2673a49f7d2d49587a2e799330ea1e30614f7c63343b35a9828d0a1ee1744d6c96e19c7aa476cc2
-  data.tar.gz: b0c71cf0f09e04982b4942b75d7dee3cee757a007a6d7279ca036fa5f81ae2216690d630f3e0a34e5ba1ea07d680f034b0d85568c5111c37805a3ff72f4d6eb5
+  metadata.gz: 7f8f6bdbe623eabacc481f8264f9d43472c1d152d2383736087102db93e6d55047506d2fd6e7ec63e6647ad03aafb6f08861fcfed5ae6e44d54acd1a722041f1
+  data.tar.gz: 2ca5412c0f1c6a4f86e53f7d53495dcf8073e85d6173a92e0dd58a40c111cd2ed1e7f658d92f1d1bbdcd194bbf8c5bc17d00fa890dfc9186ec86885baacf5991

data/.release-please-manifest.json

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

data/CHANGELOG.md

@@ -5,6 +5,13 @@ 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)
 
 

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/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/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,68 +24,9 @@ require "timeout"
 #   end
 #
 class Riffer::Tool
-  DEFAULT_TIMEOUT = 10 #: Integer
+  extend Riffer::Toolable
 
-  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)) 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.22.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/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,47 +20,7 @@
 #     end
 #   end
 class Riffer::Tool
-  DEFAULT_TIMEOUT: Integer
-
-  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.22.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