riffer 0.22.0 → 0.24.0

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.24.0" #: String
 end

data/sig/generated/riffer/agent.rbs

@@ -247,6 +247,10 @@ class Riffer::Agent
   # : ((String | Array[Hash[Symbol, untyped] | Riffer::Messages::Base]), ?files: Array[Hash[Symbol, untyped] | Riffer::FilePart]?) -> void
   def initialize_messages: (String | Array[Hash[Symbol, untyped] | Riffer::Messages::Base], ?files: Array[Hash[Symbol, untyped] | Riffer::FilePart]?) -> void
 
+  # --
+  # : (Array[Hash[Symbol, untyped] | Riffer::Messages::Base]) -> void
+  def validate_seed_ids!: (Array[Hash[Symbol, untyped] | Riffer::Messages::Base]) -> void
+
   # --
   # : (?Hash[Symbol, untyped]?) -> Riffer::Messages::System?
   def build_instruction_message: (?Hash[Symbol, untyped]?) -> Riffer::Messages::System?

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
 
@@ -52,6 +63,8 @@ class Riffer::Config
                 | ({ ?judge_model: untyped }) -> instance
   end
 
+  VALID_MESSAGE_ID_STRATEGIES: untyped
+
   # Amazon Bedrock configuration (Struct with +api_token+ and +region+).
   attr_reader amazon_bedrock: Riffer::Config::AmazonBedrock
 
@@ -61,6 +74,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
 
@@ -82,6 +98,23 @@ class Riffer::Config
   # : ((singleton(Riffer::ToolRuntime) | Riffer::ToolRuntime | Proc)) -> void
   def tool_runtime=: (singleton(Riffer::ToolRuntime) | Riffer::ToolRuntime | Proc) -> void
 
+  # Strategy for auto-generating message ids. One of +:none+ (default, no id),
+  # +:uuid+ (UUIDv4), or +:uuidv7+ (time-ordered UUIDv7).
+  #
+  # When set to anything other than +:none+, each +Riffer::Messages::Base+
+  # instance gets an +id+ populated at construction time, and seeded messages
+  # passed to +Riffer::Agent#generate+ must carry their own +:id+.
+  attr_reader message_id_strategy: Symbol
+
+  # Sets the message id strategy.
+  #
+  # Raises +Riffer::ArgumentError+ if the value is not one of
+  # +:none+, +:uuid+, or +:uuidv7+.
+  #
+  # --
+  # : (Symbol) -> void
+  def message_id_strategy=: (Symbol) -> void
+
   # --
   # : () -> void
   def initialize: () -> void

data/sig/generated/riffer/messages/assistant.rbs

@@ -30,8 +30,8 @@ class Riffer::Messages::Assistant < Riffer::Messages::Base
   attr_reader structured_output: Hash[Symbol, untyped]?
 
   # --
-  # : (String, ?tool_calls: Array[Riffer::Messages::Assistant::ToolCall], ?token_usage: Riffer::TokenUsage?, ?structured_output: Hash[Symbol, untyped]?) -> void
-  def initialize: (String, ?tool_calls: Array[Riffer::Messages::Assistant::ToolCall], ?token_usage: Riffer::TokenUsage?, ?structured_output: Hash[Symbol, untyped]?) -> void
+  # : (String, ?id: String?, ?tool_calls: Array[Riffer::Messages::Assistant::ToolCall], ?token_usage: Riffer::TokenUsage?, ?structured_output: Hash[Symbol, untyped]?) -> void
+  def initialize: (String, ?id: String?, ?tool_calls: Array[Riffer::Messages::Assistant::ToolCall], ?token_usage: Riffer::TokenUsage?, ?structured_output: Hash[Symbol, untyped]?) -> void
 
   # --
   # : () -> Symbol

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

@@ -7,9 +7,12 @@ class Riffer::Messages::Base
   # The message content.
   attr_reader content: String
 
+  # The message id, or nil when +Riffer.config.message_id_strategy+ is +:none+.
+  attr_reader id: String?
+
   # --
-  # : (String) -> void
-  def initialize: (String) -> void
+  # : (String, ?id: String?) -> void
+  def initialize: (String, ?id: String?) -> void
 
   # Converts the message to a hash.
   #
@@ -24,4 +27,9 @@ class Riffer::Messages::Base
   # --
   # : () -> Symbol
   def role: () -> Symbol
+
+  private
+
+  # : () -> String?
+  def generate_id: () -> String?
 end

data/sig/generated/riffer/messages/tool.rbs

@@ -24,8 +24,8 @@ class Riffer::Messages::Tool < Riffer::Messages::Base
   attr_reader error_type: Symbol?
 
   # --
-  # : (String, tool_call_id: String, name: String, ?error: String?, ?error_type: Symbol?) -> void
-  def initialize: (String, tool_call_id: String, name: String, ?error: String?, ?error_type: Symbol?) -> void
+  # : (String, tool_call_id: String, name: String, ?id: String?, ?error: String?, ?error_type: Symbol?) -> void
+  def initialize: (String, tool_call_id: String, name: String, ?id: String?, ?error: String?, ?error_type: Symbol?) -> void
 
   # Returns true if the tool execution resulted in an error.
   #

data/sig/generated/riffer/messages/user.rbs

@@ -15,8 +15,8 @@ class Riffer::Messages::User < Riffer::Messages::Base
   # Initializes a user message.
   #
   # --
-  # : (String, ?files: Array[Riffer::FilePart]) -> void
-  def initialize: (String, ?files: Array[Riffer::FilePart]) -> void
+  # : (String, ?id: String?, ?files: Array[Riffer::FilePart]) -> void
+  def initialize: (String, ?id: String?, ?files: Array[Riffer::FilePart]) -> void
 
   # --
   # : () -> Symbol