riffer 0.22.0 → 0.24.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e6c1902fc4a3a1ad047491befa79ae44aa7aea3e160dda3303fe18c3670e477
-  data.tar.gz: d4407ecd6a3af8900e7a2a456870e5e4a4211df016259980bf8f5b559ad8df2f
+  metadata.gz: dd2f811bba1934e2285de7f4ec122259039dcb61f6d6141e3c26992d38ba2e07
+  data.tar.gz: 877941ede9824184db9e7eb99ee901096995298937033f65c87562afeec7d208
 SHA512:
-  metadata.gz: 5845e5336564993a8e23ff6a5a1c903fb28925991443d4beb2673a49f7d2d49587a2e799330ea1e30614f7c63343b35a9828d0a1ee1744d6c96e19c7aa476cc2
-  data.tar.gz: b0c71cf0f09e04982b4942b75d7dee3cee757a007a6d7279ca036fa5f81ae2216690d630f3e0a34e5ba1ea07d680f034b0d85568c5111c37805a3ff72f4d6eb5
+  metadata.gz: 2477d9fcba22f212f7a83b6e7a400476aa7e4cc7c842d631d9044d7771827fcf903355f4015d9fa357e752ceb41a26fcfd62afd3711134c61a9745c3005dfe3c
+  data.tar.gz: d06abbd9da19f04cfc97449e72f283297ae07ab5dface13119c92cdf2121515c1de83ed6992daa1ab49ec460e15c5afaf4883b4224c9ed7c838f64b7f9ca816a

data/.agents/architecture.md

@@ -112,6 +112,7 @@ On resume, `execute_pending_tool_calls` detects tool calls from the last assista
 Concurrency primitive for batch execution. Subclasses implement `#map(items, context: nil, &block)` to control how items are processed. The `context` keyword carries the agent's context hash, enabling runners that need it for job serialization or routing.
 
 Built-in runners:
+
 - `Sequential` — processes items in the current thread via `Array#map`
 - `Threaded` — processes items concurrently using a thread pool with configurable `max_concurrency`
 
@@ -125,6 +126,7 @@ runner.map(items, context: ctx) { |item| process(item) }
 Composes with a Runner to execute tool calls. Provides `#execute` as the public entry point and `#around_tool_call` as a hook for instrumentation. Passes the agent context through to the runner.
 
 Built-in runtimes:
+
 - `Inline` — uses `Runner::Sequential` (default)
 - `Threaded` — uses `Runner::Threaded`
 

data/.release-please-manifest.json

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

data/AGENTS.md

@@ -8,6 +8,7 @@ Ruby gem framework for building AI-powered agents with LLM provider adapters.
 - **Lint + Test**: `bundle exec rake`
 - **Autoloading**: Zeitwerk (file paths must match module/class names)
 - **Model format**: `provider/model` (e.g., `openai/gpt-4`)
+- **Docs**: when adding a public config option or message attribute, update the matching page in `docs/` (e.g., `docs/10_CONFIGURATION.md`, `docs/08_MESSAGES.md`). RDoc ≠ user docs.
 
 ## Topic Guides
 
@@ -20,12 +21,12 @@ Ruby gem framework for building AI-powered agents with LLM provider adapters.
 
 ## Commands
 
-| Command | Description |
-|---------|-------------|
-| `bundle exec rake` | Run tests + lint (default) |
-| `bundle exec rake test` | Run tests only |
-| `bundle exec rake standard` | Check code style |
-| `bundle exec rake standard:fix` | Auto-fix style issues |
-| `bundle exec rake rbs:generate` | Generate RBS type signatures |
-| `bundle exec rake rbs:watch` | Watch and regenerate RBS files |
-| `bin/console` | Interactive console |
+| Command                         | Description                    |
+| ------------------------------- | ------------------------------ |
+| `bundle exec rake`              | Run tests + lint (default)     |
+| `bundle exec rake test`         | Run tests only                 |
+| `bundle exec rake standard`     | Check code style               |
+| `bundle exec rake standard:fix` | Auto-fix style issues          |
+| `bundle exec rake rbs:generate` | Generate RBS type signatures   |
+| `bundle exec rake rbs:watch`    | Watch and regenerate RBS files |
+| `bin/console`                   | Interactive console            |

data/CHANGELOG.md

@@ -5,6 +5,20 @@ 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.24.0](https://github.com/janeapp/riffer/compare/riffer/v0.23.0...riffer/v0.24.0) (2026-04-20)
+
+
+### Features
+
+* add optional message id generation ([#210](https://github.com/janeapp/riffer/issues/210)) ([0f9e20d](https://github.com/janeapp/riffer/commit/0f9e20dcd2d69a49fe5da71be3f0b9deb0a046a4))
+
+## [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/Steepfile

@@ -5,10 +5,13 @@ target :lib do
 
   check "lib"
 
-  library "logger"
   library "anthropic"
-  library "openai"
   library "aws-sdk-bedrockruntime"
+  library "aws-sdk-core"
+  library "logger"
+  library "net-http"
+  library "openai"
+  library "uri"
 
   configure_code_diagnostics(D::Ruby.lenient)
 end

data/docs/08_MESSAGES.md

@@ -252,12 +252,12 @@ Without this step, the same model can receive different input depending on the p
 
 ### Merge rules
 
-| Message type | Content | Auxiliary data | Merged? |
-|--------------|---------|----------------|---------|
-| `System` | Joined with `"\n\n"` | — | Yes |
-| `User` | Joined with `"\n\n"` | `files` arrays concatenated | Yes |
-| `Assistant` | Joined with `"\n\n"` | `tool_calls` arrays concatenated | Yes |
-| `Tool` | — | — | Never (each has a unique `tool_call_id`) |
+| Message type | Content              | Auxiliary data                   | Merged?                                  |
+| ------------ | -------------------- | -------------------------------- | ---------------------------------------- |
+| `System`     | Joined with `"\n\n"` | —                                | Yes                                      |
+| `User`       | Joined with `"\n\n"` | `files` arrays concatenated      | Yes                                      |
+| `Assistant`  | Joined with `"\n\n"` | `tool_calls` arrays concatenated | Yes                                      |
+| `Tool`       | —                    | —                                | Never (each has a unique `tool_call_id`) |
 
 ### Example
 
@@ -278,20 +278,50 @@ agent.generate(messages)
 
 Merging happens at serialization time only. The agent's `messages` array still contains the original separate messages for logging, evals, and debugging.
 
+## IDs
+
+Every message carries an optional `id` attribute. By default ids are disabled (`message.id` returns `nil` and `:id` is omitted from `to_h`). Enable them globally by setting `Riffer.config.message_id_strategy`:
+
+```ruby
+Riffer.configure { |c| c.message_id_strategy = :uuidv7 }
+
+msg = Riffer::Messages::User.new("Hello")
+msg.id     # => "0195a2e1-..." (auto-generated UUIDv7)
+msg.to_h   # => {role: :user, content: "Hello", id: "0195a2e1-..."}
+```
+
+Supported strategies: `:none` (default), `:uuid`, `:uuidv7`. See [Configuration — Message ID Strategy](10_CONFIGURATION.md#message-id-strategy) for the full reference.
+
+Ids pass through to subclass constructors via an `id:` kwarg and are preserved when set explicitly:
+
+```ruby
+msg = Riffer::Messages::Assistant.new("Done.", id: "reply-42")
+msg.id  # => "reply-42"
+```
+
+When seeding an agent with existing conversation history and the strategy is enabled, every seeded message must include an id — Riffer raises `Riffer::ArgumentError` on missing ids rather than fabricating them.
+
 ## Base Class
 
 All messages inherit from `Riffer::Messages::Base`:
 
 ```ruby
 class Riffer::Messages::Base
-  attr_reader :content
+  attr_reader :content, :id
+
+  def initialize(content, id: nil)
+    @content = content
+    @id = id || generate_id  # uses Riffer.config.message_id_strategy
+  end
 
   def role
     raise NotImplementedError
   end
 
   def to_h
-    {role: role, content: content}
+    hash = {role: role, content: content}
+    hash[:id] = id unless id.nil?
+    hash
   end
 end
 ```

data/docs/10_CONFIGURATION.md

@@ -54,6 +54,39 @@ end
 
 Per-agent configuration overrides this global default. See [Advanced Tool Configuration — Tool Runtime](07_TOOL_ADVANCED.md#tool-runtime-experimental) for details.
 
+### Message ID Strategy
+
+Opt in to stable identifiers on every message for logging, persistence, or replay:
+
+```ruby
+Riffer.configure do |config|
+  config.message_id_strategy = :uuidv7
+end
+```
+
+| Value             | Description                                                                      |
+| ----------------- | -------------------------------------------------------------------------------- |
+| `:none` (default) | No id is generated; `message.id` returns `nil` and `:id` is omitted from `to_h`. |
+| `:uuid`           | UUIDv4 via `SecureRandom.uuid`.                                                  |
+| `:uuidv7`         | Time-ordered UUIDv7 via `SecureRandom.uuid_v7` (Ruby 3.3+).                      |
+
+When the strategy is not `:none`, every `Riffer::Messages::Base` instance — user prompts, system instructions, assistant responses, and tool results — gets an auto-generated `id` at construction time. IDs are included in `message.to_h` when present and omitted when `nil`. Provider API payloads are unaffected; the `id` stays on the Ruby side.
+
+Seeded messages passed to `agent.generate([...])` must carry their own `:id` when the strategy is enabled — Riffer never fabricates identifiers for pre-existing history:
+
+```ruby
+Riffer.configure { |c| c.message_id_strategy = :uuidv7 }
+
+agent.generate([
+  {role: :user, content: "Hi", id: "msg-001"},
+  {role: :assistant, content: "Hello!", id: "msg-002"}
+])
+```
+
+Missing ids raise `Riffer::ArgumentError` with the offending index.
+
+See [Messages — IDs](08_MESSAGES.md#ids) for more details.
+
 ## Agent-Level Configuration
 
 Override global configuration at the agent level:

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/agent.rb

@@ -176,7 +176,7 @@ class Riffer::Agent
   #--
   #: (String) -> singleton(Riffer::Agent)?
   def self.find(identifier)
-    subclasses.find { |agent_class| agent_class.identifier == identifier.to_s }
+    all.find { |agent_class| agent_class.identifier == identifier.to_s }
   end
 
   # Returns all agent subclasses.
@@ -184,7 +184,7 @@ class Riffer::Agent
   #--
   #: () -> Array[singleton(Riffer::Agent)]
   def self.all
-    subclasses
+    subclasses #: Array[singleton(Riffer::Agent)]
   end
 
   # Generates a response using a new agent instance.
@@ -433,6 +433,7 @@ class Riffer::Agent
     if prompt_or_messages.is_a?(Array)
       raise Riffer::ArgumentError, "cannot pass an array of messages on an agent with existing messages; use a string to continue the conversation or a new agent instance to start fresh" if @messages.any?
       raise Riffer::ArgumentError, "cannot provide both files and messages; attach files to individual messages instead" if files && !files.empty?
+      validate_seed_ids!(prompt_or_messages)
       @messages = prompt_or_messages.map { |item| convert_to_message_object(item) }
     elsif @messages.any?
       file_parts = (files || []).map { |f| convert_to_file_part(f) }
@@ -448,6 +449,24 @@ class Riffer::Agent
     end
   end
 
+  #--
+  #: (Array[Hash[Symbol, untyped] | Riffer::Messages::Base]) -> void
+  def validate_seed_ids!(items)
+    strategy = Riffer.config.message_id_strategy
+    return if strategy == :none
+
+    items.each_with_index do |item, idx|
+      raw_id = case item
+      when Hash then item[:id]
+      when Riffer::Messages::Base then item.id
+      else next # type errors surface later via convert_to_message_object
+      end
+      next unless raw_id.nil?
+      raise Riffer::ArgumentError,
+        "seeded message at index #{idx} is missing :id (required when Riffer.config.message_id_strategy = #{strategy.inspect})"
+    end
+  end
+
   #--
   #: (?Hash[Symbol, untyped]?) -> Riffer::Messages::System?
   def build_instruction_message(context = @context)
@@ -783,7 +802,7 @@ class Riffer::Agent
   #--
   #: () -> Riffer::Messages::Assistant?
   def extract_final_response
-    @messages.reverse.find { |msg| msg.is_a?(Riffer::Messages::Assistant) }
+    @messages.reverse.find { |msg| msg.is_a?(Riffer::Messages::Assistant) } #: Riffer::Messages::Assistant?
   end
 
   #--

data/lib/riffer/config.rb

@@ -18,9 +18,12 @@ 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)
 
+  VALID_MESSAGE_ID_STRATEGIES = %i[none uuid uuidv7].freeze
+
   # Amazon Bedrock configuration (Struct with +api_token+ and +region+).
   attr_reader :amazon_bedrock #: Riffer::Config::AmazonBedrock
 
@@ -30,6 +33,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
 
@@ -55,14 +61,39 @@ class Riffer::Config
     @tool_runtime = value
   end
 
+  # 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=(value)
+    unless VALID_MESSAGE_ID_STRATEGIES.include?(value)
+      raise Riffer::ArgumentError,
+        "message_id_strategy must be one of #{VALID_MESSAGE_ID_STRATEGIES.inspect}, got #{value.inspect}"
+    end
+    @message_id_strategy = value
+  end
+
   #--
   #: () -> void
   def initialize
     @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
+    @message_id_strategy = :none
   end
 end

data/lib/riffer/messages/assistant.rb

@@ -23,9 +23,9 @@ 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(content, tool_calls: [], token_usage: nil, structured_output: nil)
-    super(content)
+  #: (String, ?id: String?, ?tool_calls: Array[Riffer::Messages::Assistant::ToolCall], ?token_usage: Riffer::TokenUsage?, ?structured_output: Hash[Symbol, untyped]?) -> void
+  def initialize(content, id: nil, tool_calls: [], token_usage: nil, structured_output: nil)
+    super(content, id: id)
     @tool_calls = tool_calls
     @token_usage = token_usage
     @structured_output = structured_output
@@ -55,6 +55,7 @@ class Riffer::Messages::Assistant < Riffer::Messages::Base
   #: () -> Hash[Symbol, untyped]
   def to_h
     hash = {role: role, content: content}
+    hash[:id] = id unless id.nil?
     hash[:tool_calls] = tool_calls.map(&:to_h) unless tool_calls.empty?
     hash[:token_usage] = token_usage.to_h if token_usage
     hash[:structured_output] = structured_output if structured_output?

data/lib/riffer/messages/base.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
+require "securerandom"
+
 # Base class for all message types in the Riffer framework.
 #
 # Subclasses must implement the +role+ method.
@@ -8,10 +10,14 @@ 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(content)
+  #: (String, ?id: String?) -> void
+  def initialize(content, id: nil)
     @content = content
+    @id = id || generate_id
   end
 
   # Converts the message to a hash.
@@ -19,7 +25,9 @@ class Riffer::Messages::Base
   #--
   #: () -> Hash[Symbol, untyped]
   def to_h
-    {role: role, content: content}
+    hash = {role: role, content: content}
+    hash[:id] = id unless id.nil?
+    hash
   end
 
   # Returns the message role.
@@ -31,4 +39,14 @@ class Riffer::Messages::Base
   def role
     raise NotImplementedError, "Subclasses must implement #role"
   end
+
+  private
+
+  #: () -> String?
+  def generate_id
+    case Riffer.config.message_id_strategy
+    when :uuid then SecureRandom.uuid
+    when :uuidv7 then SecureRandom.uuid_v7
+    end
+  end
 end

data/lib/riffer/messages/converter.rb

@@ -65,22 +65,24 @@ module Riffer::Messages::Converter
       raise Riffer::ArgumentError, "Message hash must include a 'role' key"
     end
 
+    id = hash[:id]
+
     case role.to_sym
     when :user
       files = (hash[:files] || []).map { |f| convert_to_file_part(f) }
-      Riffer::Messages::User.new(content, files: files)
+      Riffer::Messages::User.new(content, id: id, files: files)
     when :assistant
       tool_calls = (hash[:tool_calls] || []).map { |tc|
         tc.is_a?(Riffer::Messages::Assistant::ToolCall) ? tc : Riffer::Messages::Assistant::ToolCall.new(**tc)
       }
       structured_output = hash[:structured_output]
-      Riffer::Messages::Assistant.new(content, tool_calls: tool_calls, structured_output: structured_output)
+      Riffer::Messages::Assistant.new(content, id: id, tool_calls: tool_calls, structured_output: structured_output)
     when :system
-      Riffer::Messages::System.new(content)
+      Riffer::Messages::System.new(content, id: id)
     when :tool
       tool_call_id = hash[:tool_call_id]
       name = hash[:name]
-      Riffer::Messages::Tool.new(content, tool_call_id: tool_call_id, name: name)
+      Riffer::Messages::Tool.new(content, id: id, tool_call_id: tool_call_id, name: name)
     else
       raise Riffer::ArgumentError, "Unknown message role: #{role}"
     end

data/lib/riffer/messages/tool.rb

@@ -26,9 +26,9 @@ 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(content, tool_call_id:, name:, error: nil, error_type: nil)
-    super(content)
+  #: (String, tool_call_id: String, name: String, ?id: String?, ?error: String?, ?error_type: Symbol?) -> void
+  def initialize(content, tool_call_id:, name:, id: nil, error: nil, error_type: nil)
+    super(content, id: id)
     @tool_call_id = tool_call_id
     @name = name
     @error = error
@@ -55,6 +55,7 @@ class Riffer::Messages::Tool < Riffer::Messages::Base
   #: () -> Hash[Symbol, untyped]
   def to_h
     hash = {role: role, content: content, tool_call_id: tool_call_id, name: name}
+    hash[:id] = id unless id.nil?
     if error?
       hash[:error] = error
       hash[:error_type] = error_type

data/lib/riffer/messages/user.rb

@@ -17,9 +17,9 @@ class Riffer::Messages::User < Riffer::Messages::Base
   # Initializes a user message.
   #
   #--
-  #: (String, ?files: Array[Riffer::FilePart]) -> void
-  def initialize(content, files: [])
-    super(content)
+  #: (String, ?id: String?, ?files: Array[Riffer::FilePart]) -> void
+  def initialize(content, id: nil, files: [])
+    super(content, id: id)
     @files = files
   end
 
@@ -39,6 +39,7 @@ class Riffer::Messages::User < Riffer::Messages::Base
   #: () -> Hash[Symbol, untyped]
   def to_h
     hash = {role: role, content: content}
+    hash[:id] = id unless id.nil?
     hash[:files] = files.map(&:to_h) unless files.empty?
     hash
   end