phronomy 0.27.0 → 0.28.0

data/lib/phronomy/generation/generator_verifier.rb

@@ -20,7 +20,7 @@ module Phronomy
       alias_method :trusted?, :trusted
     end
 
-    private_constant :PipelineState, :WorkflowBuilder, :AgentResultReceiver
+    private_constant :PipelineState, :WorkflowBuilder, :AgentResultReceiver, :AgentOperation
 
     def initialize(
       draft_agent:,
@@ -80,8 +80,8 @@ module Phronomy
 
     def build_workflow
       WorkflowBuilder.new(
-        draft_agent: @draft_agent_class.new,
-        review_agent: @review_agent_class.new,
+        draft_agent: AgentOperation.new(@draft_agent_class),
+        review_agent: AgentOperation.new(@review_agent_class),
         draft_prompt_builder: @draft_prompt_builder,
         review_prompt_builder: @review_prompt_builder,
         draft_result_parser: @draft_result_parser,
@@ -92,7 +92,7 @@ module Phronomy
     end
 
     def default_parse_draft(text)
-      json_parser.parse(text)
+      default_parser.parse(text)
     rescue Phronomy::ParseError
       {
         answer: text.to_s,
@@ -102,7 +102,7 @@ module Phronomy
     end
 
     def default_parse_review(text)
-      json_parser.parse(text)
+      default_parser.parse(text)
     rescue Phronomy::ParseError
       {
         approved: false,
@@ -111,8 +111,8 @@ module Phronomy
       }
     end
 
-    def json_parser
-      @json_parser ||= Phronomy::OutputParser::JsonParser.new
+    def default_parser
+      @default_parser ||= DefaultParser.build
     end
   end
 end

data/lib/phronomy/llm_adapter/async/async_client.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module LLMAdapter
+    # Offloads the entire operation, including SDK initialization and decoding.
+    # Construction does not start a Runtime.
+    # @api private
+    class AsyncClient
+      # @api private
+      def initialize(adapter:, pool: nil, submitter: Phronomy::Execution)
+        @adapter = adapter
+        @pool = pool
+        @submitter = submitter
+      end
+
+      # @api private
+      def complete_async(request, cancellation_token: nil, pool: @pool)
+        submit(pool, cancellation_token) do
+          @adapter.complete(request, cancellation_token: cancellation_token)
+        end
+      end
+
+      # The block is an internal event sink, never an Application callback.
+      # @api private
+      def stream_async(request, cancellation_token: nil, pool: @pool, &block)
+        raise ArgumentError, "stream_async requires a block" unless block
+        submit(pool, cancellation_token) do
+          @adapter.stream(request, cancellation_token: cancellation_token) do |chunk|
+            cancellation_token&.raise_if_cancelled!
+            block.call(chunk)
+          end
+        end
+      end
+
+      private
+
+      def submit(pool, cancellation_token, &operation)
+        if pool
+          Phronomy::Execution.submit(pool: pool, cancellation_token: cancellation_token,
+            on_full: :raise, &operation)
+        else
+          @submitter.submit(cancellation_token: cancellation_token, on_full: :raise, &operation)
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/{llm_contract → llm_adapter}/authentication_error.rb

@@ -3,5 +3,7 @@
 require_relative "transport_error"
 
 module Phronomy
-  class AuthenticationError < TransportError; end
+  module LLMAdapter
+    class AuthenticationError < TransportError; end
+  end
 end

data/lib/phronomy/llm_adapter/backends/ruby_llm.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require "ruby_llm"
+
+module Phronomy
+  module LLMAdapter
+    # SDK objects are operation-local. Only Phronomy request/result values cross
+    # the backend boundary; a Tool definition never contains executable work.
+    # @api public
+    class RubyLLM < Base
+      ToolsRequested = Class.new(StandardError) do
+        attr_reader :message_value
+        def initialize(message_value)
+          @message_value = message_value
+          super("assistant requested Tools")
+        end
+      end
+      private_constant :ToolsRequested
+
+      # @api public
+      def identity
+        super.merge("sdk_version" => ::RubyLLM::VERSION).freeze
+      end
+
+      # @api public
+      def input_budget(model_config)
+        config = model_config.to_h.transform_keys(&:to_s)
+        return nil unless config["model"]
+        model = ::RubyLLM.models.find(config["model"], provider: config["provider"])
+        limit = model&.context_window
+        return nil unless limit.is_a?(Integer) && limit.positive?
+        Phronomy::LlmContextWindow::TokenBudget.new(max_input_tokens: limit)
+      rescue ::RubyLLM::ModelNotFoundError
+        nil
+      rescue => error
+        raise_provider_error(error)
+      end
+
+      protected
+
+      # @api public
+      def perform_complete(request, cancellation_token:)
+        execute_request(request, cancellation_token)
+      end
+
+      # @api public
+      def perform_stream(request, cancellation_token:, &block)
+        execute_request(request, cancellation_token, &block)
+      end
+
+      private
+
+      def execute_request(request, token)
+        callback_error = nil
+        chat = build_chat(request)
+        token&.raise_if_cancelled!
+        chat.after_message do |message|
+          raise ToolsRequested.new(message) if message.tool_call?
+        end
+        response = if block_given?
+          sink = proc do |chunk|
+            token&.raise_if_cancelled!
+            value = stream_value(chunk)
+            begin
+              yield value
+            rescue => error
+              callback_error = error
+              raise
+            end
+          end
+          request.message ? chat.ask(request.message, &sink) : chat.complete(&sink)
+        else
+          request.message ? chat.ask(request.message) : chat.complete
+        end
+        response_value(response)
+      rescue ToolsRequested => requested
+        response_value(requested.message_value)
+      rescue => error
+        raise error if error.equal?(callback_error)
+        raise_provider_error(error)
+      end
+
+      def build_chat(request)
+        config = request.model_config
+        options = {}
+        options[:model] = config["model"] if config["model"]
+        if config["provider"]
+          options[:provider] = config["provider"].to_sym
+          options[:assume_model_exists] = config.fetch("assume_model_exists", true)
+        elsif config.key?("assume_model_exists")
+          options[:assume_model_exists] = config["assume_model_exists"]
+        end
+        chat = ::RubyLLM.chat(**options)
+        chat.with_temperature(config["temperature"]) if config["temperature"]
+        chat.with_max_output_tokens(config["max_output_tokens"]) if config["max_output_tokens"]
+        if request.system
+          chat.with_instructions(request.system, cache_until_here: config["cache_instructions"])
+        end
+        request.tools.each { |definition| chat.with_tools(tool_declaration(definition)) }
+        request.messages.each { |value| chat.messages << sdk_message(value) }
+        chat
+      end
+
+      def tool_declaration(definition)
+        name = definition.fetch("name")
+        klass = Class.new(::RubyLLM::Tool) do
+          define_singleton_method(:tool_name) { name }
+          define_method(:execute) do |**_arguments|
+            raise InvalidResultError, "SDK attempted to execute a declaration-only Tool"
+          end
+        end
+        klass.description(definition.fetch("description"))
+        klass.parameters(definition.fetch("parameters_schema"))
+        klass.provider_options(definition.fetch("provider_options", {}))
+        klass
+      end
+
+      def sdk_message(value)
+        calls = value.tool_calls.to_h do |call|
+          [call.id, ::RubyLLM::ToolCall.new(id: call.id, name: call.name,
+            arguments: call.arguments, thought_signature: call.metadata["thought_signature"])]
+        end
+        content = value.content
+        content = JSON.generate(content) if content.is_a?(Hash) || content.is_a?(Array)
+        content = "" if value.role == :assistant && content.nil? && !calls.empty?
+        ::RubyLLM::Message.new(role: value.role, content: content,
+          tool_calls: calls.empty? ? nil : calls, tool_call_id: value.tool_call_id,
+          model: value.metadata["model_id"])
+      end
+
+      def response_value(message)
+        unless message.respond_to?(:content) && message.respond_to?(:role) && message.role.to_sym == :assistant
+          raise InvalidResultError, "provider returned an invalid assistant message"
+        end
+        raw_calls = message.tool_calls if message.respond_to?(:tool_calls)
+        calls = raw_calls.is_a?(Hash) ? raw_calls.values : (raw_calls || [])
+        raise InvalidResultError, "provider returned invalid Tool calls" unless calls.is_a?(Array)
+        calls = calls.map do |call|
+          metadata = {}
+          if call.respond_to?(:thought_signature) && call.thought_signature
+            metadata["thought_signature"] = call.thought_signature
+          end
+          Phronomy::Tool::CallRequest.new(id: call.id, name: call.name,
+            arguments: call.arguments, metadata: metadata)
+        end
+        tokens = message.tokens if message.respond_to?(:tokens)
+        usage = Phronomy::LLMAdapter::TokenUsage.new(
+          input: tokens&.input, output: tokens&.output,
+          cached: tokens&.cache_read, cache_creation: tokens&.cache_write
+        )
+        metadata = {}
+        metadata["model_id"] = message.model if message.respond_to?(:model) && message.model
+        Response.new(content: message.content, tool_calls: calls, usage: usage, metadata: metadata)
+      rescue ArgumentError, TypeError, NoMethodError => error
+        raise InvalidResultError, "malformed provider response: #{error.message}"
+      end
+
+      def stream_value(chunk)
+        raise InvalidResultError, "provider returned an invalid stream chunk" unless chunk.respond_to?(:content)
+        StreamChunk.new(content: chunk.content)
+      rescue ArgumentError => error
+        raise InvalidResultError, "malformed provider chunk: #{error.message}"
+      end
+
+      # Translate SDK errors only. Cancellation and callback failures retain
+      # identity; raising here preserves the original provider exception cause.
+      def raise_provider_error(error)
+        case error
+        when ::RubyLLM::RateLimitError
+          raise Phronomy::LLMAdapter::RateLimitError, error.message
+        when ::RubyLLM::UnauthorizedError, ::RubyLLM::ForbiddenError
+          raise Phronomy::LLMAdapter::AuthenticationError, error.message
+        when ::RubyLLM::ContextLengthExceededError
+          raise Phronomy::LLMAdapter::ContextLengthError, error.message
+        when ::RubyLLM::Error
+          raise Phronomy::LLMAdapter::TransportError, error.message
+        else
+          raise error
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/llm_adapter/base.rb

@@ -1,91 +1,72 @@
 # frozen_string_literal: true
 
+require_relative "request"
+require_relative "response"
+require_relative "stream_chunk"
+require_relative "invalid_result_error"
+
 module Phronomy
   module LLMAdapter
-    # Beta extension SPI for LLM call adapters.
-    #
-    # External adapters implement {#complete} and {#stream}. The adapter or the
-    # underlying provider client owns transport timeout, retry, backoff, and
-    # rate-limit behavior. Phronomy owns cooperative cancellation and isolates
-    # synchronous provider calls in {OffloadPool}.
-    #
-    # The Agent pipeline calls the framework-owned {#complete_async} and
-    # {#stream_async} wrappers. Adapter implementers do not need to depend on
-    # EventLoop, FSMSession, OffloadPool, AgentInvocation, or ExecutionCoordinator.
-    #
-    # The current input to this SPI is the configured/materialized chat runtime
-    # object. Formalizing this SPI therefore does not imply a provider-neutral
-    # replacement for RubyLLMMaterializer.
-    #
+    # Owns one-turn operations. Backends implement protected synchronous hooks.
+    # SDK construction and translation happen entirely inside those hooks.
     # @api public
     class Base
-      # Performs a blocking (non-streaming) LLM completion.
-      #
-      # Implementors call the configured chat/runtime client and return its
-      # response object. Transport/retry policy remains adapter-owned.
-      #
-      # @param chat    [Object] the configured/materialized chat runtime object
-      # @param message [String, nil] user message, or nil to continue without adding a new user turn
-      # @param config  [Hash] invocation config (e.g. +:cancellation_token+)
-      # @return [Object] LLM response object
-      # @raise [NotImplementedError]
       # @api public
-      def complete(chat, message, config: {})
-        raise NotImplementedError, "#{self.class}#complete is not implemented"
+      def identity
+        {"adapter_name" => self.class.name}.freeze
+      end
+
+      # Local model metadata only. Missing capacity is permitted.
+      # @api public
+      def input_budget(model_config)
+        nil
       end
 
-      # Performs a blocking streaming LLM completion.
-      #
-      # @param chat    [Object] the configured/materialized chat runtime object
-      # @param message [String, nil] user message, or nil to continue without adding a new user turn
-      # @param config  [Hash] invocation config
-      # @yield [chunk] streaming chunk from the LLM
-      # @return [Object] LLM response object
-      # @raise [NotImplementedError]
       # @api public
-      def stream(chat, message, config: {}, &block)
-        raise NotImplementedError, "#{self.class}#stream is not implemented"
+      def complete(request, cancellation_token: nil)
+        validate_request!(request, cancellation_token)
+        response = perform_complete(request, cancellation_token: cancellation_token)
+        cancellation_token&.raise_if_cancelled!
+        validate_response!(response)
       end
 
-      # Submits a non-streaming LLM call to {OffloadPool}.
-      #
-      # Transport timeout and retry remain the responsibility of the adapter or
-      # provider client; Phronomy does not attach an additional operation timeout.
-      #
-      # @return [Phronomy::TaskResult] caller-facing completion handle
-      # @api private
-      def complete_async(chat, message, config: {}, pool: default_pool)
-        token = config[:cancellation_token]
-        pool.submit(cancellation_token: token, on_full: :raise) do
-          complete(chat, message, config: config)
+      # Notifications run on the caller thread. AsyncClient supplies an internal
+      # event sink; application callbacks remain with their owning domain.
+      # @api public
+      def stream(request, cancellation_token: nil)
+        raise ArgumentError, "stream requires a block" unless block_given?
+        validate_request!(request, cancellation_token)
+        response = perform_stream(request, cancellation_token: cancellation_token) do |chunk|
+          cancellation_token&.raise_if_cancelled!
+          raise InvalidResultError, "stream must yield StreamChunk values" unless chunk.is_a?(StreamChunk)
+          yield chunk
         end
+        cancellation_token&.raise_if_cancelled!
+        validate_response!(response)
       end
 
-      # Submits a streaming LLM call to {OffloadPool}.
-      #
-      # The block is invoked on an OffloadPool worker thread. Agent code must pass
-      # only a lightweight internal sink that posts a value to EventLoop;
-      # application callbacks must never be passed directly to this method.
-      #
-      # @yield [chunk] streaming chunk on the worker thread
-      # @return [Phronomy::TaskResult] caller-facing completion handle
-      # @api private
-      def stream_async(chat, message, config: {}, pool: default_pool, &block)
-        raise ArgumentError, "stream_async requires a block" unless block
+      protected
 
-        token = config[:cancellation_token]
-        pool.submit(cancellation_token: token, on_full: :raise) do
-          stream(chat, message, config: config) do |chunk|
-            token&.raise_if_cancelled!("invocation cancelled during streaming")
-            block.call(chunk)
-          end
-        end
+      # @api public
+      def perform_complete(request, cancellation_token:)
+        raise NotImplementedError, "#{self.class}#perform_complete is not implemented"
+      end
+
+      # @api public
+      def perform_stream(request, cancellation_token:, &block)
+        raise NotImplementedError, "#{self.class}#perform_stream is not implemented"
       end
 
       private
 
-      def default_pool
-        Phronomy::Runtime.instance.offload
+      def validate_request!(request, token)
+        token&.raise_if_cancelled!
+        raise ArgumentError, "LLM operation requires a Request" unless request.is_a?(Request)
+      end
+
+      def validate_response!(response)
+        raise InvalidResultError, "LLM operation must return a Response" unless response.is_a?(Response)
+        response
       end
     end
   end

data/lib/phronomy/{llm_contract → llm_adapter}/context_length_error.rb

@@ -3,5 +3,7 @@
 require_relative "../common/error"
 
 module Phronomy
-  class ContextLengthError < Error; end
+  module LLMAdapter
+    class ContextLengthError < Phronomy::Error; end
+  end
 end

data/lib/phronomy/llm_adapter/invalid_result_error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "../common/error"
+
+module Phronomy
+  module LLMAdapter
+    # @api public
+    class InvalidResultError < Phronomy::Error; end
+  end
+end

data/lib/phronomy/llm_adapter/message.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require_relative "../common/values/immutable"
+require_relative "../tool/schema"
+require_relative "../tool/call_request"
+
+module Phronomy
+  module LLMAdapter
+    # Provider-independent conversation value, with no executable capabilities.
+    # @api public
+    class Message
+      attr_reader :role, :content, :tool_calls, :tool_call_id, :metadata
+
+      # @api public
+      def initialize(role:, content: nil, tool_calls: [], tool_call_id: nil, metadata: {})
+        unless role.respond_to?(:to_sym) && %i[system user assistant tool].include?(role.to_sym)
+          raise ArgumentError, "invalid LLM message role"
+        end
+        unless content.nil? || content.is_a?(String) || content.is_a?(Array) || content.is_a?(Hash)
+          raise ArgumentError, "LLM content must be text, structured JSON or nil"
+        end
+        unless tool_calls.is_a?(Array) && tool_calls.all? { |call| call.is_a?(Phronomy::Tool::CallRequest) }
+          raise ArgumentError, "LLM Tool calls must be Tool::CallRequest values"
+        end
+        ids = tool_calls.map(&:id)
+        raise ArgumentError, "duplicate LLM Tool call id" unless ids.uniq == ids
+        raise ArgumentError, "only assistant messages can request Tools" if !tool_calls.empty? && role.to_sym != :assistant
+        if role.to_sym == :tool && (!tool_call_id.is_a?(String) || tool_call_id.empty?)
+          raise ArgumentError, "Tool message requires tool_call_id"
+        end
+        unless tool_call_id.nil? || tool_call_id.is_a?(String)
+          raise ArgumentError, "tool_call_id must be a String"
+        end
+        raise ArgumentError, "LLM metadata must be a Hash" unless metadata.is_a?(Hash)
+        Phronomy::Values::Immutable.validate_canonical_json!(content, label: "LLM content")
+        Phronomy::Values::Immutable.validate_canonical_json!(metadata, label: "LLM metadata")
+        @role = role.to_sym
+        @content = Phronomy::Values::Immutable.copy(content)
+        @tool_calls = tool_calls.dup.freeze
+        @tool_call_id = tool_call_id&.dup&.freeze
+        @metadata = Phronomy::Values::Immutable.copy(metadata)
+        freeze
+      end
+
+      # @api public
+      def tool_call?
+        !tool_calls.empty?
+      end
+
+      # @api public
+      def content_present?
+        !content.nil? && !content.empty?
+      end
+
+      # @api public
+      def to_h
+        {"role" => role.to_s, "content" => content, "tool_calls" => tool_calls.map(&:to_h),
+         "tool_call_id" => tool_call_id, "metadata" => metadata}.compact
+      end
+    end
+  end
+end

data/lib/phronomy/{llm_contract → llm_adapter}/rate_limit_error.rb

@@ -3,5 +3,7 @@
 require_relative "transport_error"
 
 module Phronomy
-  class RateLimitError < TransportError; end
+  module LLMAdapter
+    class RateLimitError < TransportError; end
+  end
 end

data/lib/phronomy/llm_adapter/request.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require_relative "message"
+
+module Phronomy
+  module LLMAdapter
+    # Immutable input for one model turn, including inert Tool definitions.
+    # @api public
+    class Request
+      attr_reader :model_config, :system, :messages, :tools, :message
+
+      # @api public
+      def initialize(model_config: {}, system: nil, messages: [], tools: [], message: nil)
+        if !(model_config.is_a?(Hash) && (system.nil? || system.is_a?(String)) && (message.nil? || message.is_a?(String)))
+          raise ArgumentError, "invalid LLM request configuration or text"
+        end
+        unless messages.is_a?(Array) && messages.all? { |item| item.is_a?(Message) }
+          raise ArgumentError, "LLM request messages must be Message values"
+        end
+        unless tools.is_a?(Array) && tools.all? { |tool| tool.is_a?(Hash) }
+          raise ArgumentError, "LLM request tools must be definition Hashes"
+        end
+        normalized_tools = tools.map do |definition|
+          definition = normalize_keys(definition)
+          name = definition["name"]
+          unless name.is_a?(String) && !name.empty? && definition["description"].is_a?(String)
+            raise ArgumentError, "Tool definition requires name and description"
+          end
+          if definition.key?("provider_options") && !definition["provider_options"].is_a?(Hash)
+            raise ArgumentError, "Tool provider_options must be a Hash"
+          end
+          Phronomy::Tool::Schema.new(definition.fetch("parameters_schema"))
+          Phronomy::Values::Immutable.validate_canonical_json!(definition, label: "Tool definition")
+          definition
+        end
+        names = normalized_tools.map { |tool| tool.fetch("name") }
+        raise ArgumentError, "duplicate Tool definition name" unless names.uniq == names
+        config = normalize_keys(model_config)
+        Phronomy::Values::Immutable.validate_canonical_json!(config, label: "LLM model configuration")
+        max = config["max_output_tokens"]
+        if !max.nil? && (!max.is_a?(Integer) || max <= 0)
+          raise ArgumentError, "max_output_tokens must be a positive Integer"
+        end
+        %w[model provider].each do |key|
+          value = config[key]
+          if !(value.nil? || (value.is_a?(String) && !value.empty?))
+            raise ArgumentError, "#{key} must be a non-empty String or nil"
+          end
+        end
+        %w[assume_model_exists cache_instructions].each do |key|
+          raise ArgumentError, "#{key} must be boolean or nil" unless [true, false, nil].include?(config[key])
+        end
+        temperature = config["temperature"]
+        if !(temperature.nil? || (temperature.is_a?(Numeric) && temperature.finite?))
+          raise ArgumentError, "temperature must be a finite number or nil"
+        end
+        @model_config = Phronomy::Values::Immutable.copy(config)
+        @system = system&.dup&.freeze
+        @message = message&.dup&.freeze
+        @messages = messages.dup.freeze
+        @tools = Phronomy::Values::Immutable.copy(normalized_tools)
+        freeze
+      end
+
+      private
+
+      def normalize_keys(value)
+        value.each_with_object({}) do |(key, child), result|
+          unless key.is_a?(String) || key.is_a?(Symbol)
+            raise ArgumentError, "LLM configuration/definition keys must be Strings or Symbols"
+          end
+          name = key.to_s
+          raise ArgumentError, "duplicate LLM configuration/definition key: #{name}" if result.key?(name)
+          result[name] = child
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/llm_adapter/response.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "message"
+require_relative "token_usage"
+
+module Phronomy
+  module LLMAdapter
+    # Completed assistant turn. Tool requests do not authorize execution.
+    # @api public
+    class Response < Message
+      attr_reader :usage
+
+      # @api public
+      def initialize(content: nil, tool_calls: [], usage: Phronomy::LLMAdapter::TokenUsage.new, metadata: {}, role: :assistant)
+        raise ArgumentError, "LLM response must be an assistant message" unless role == :assistant || role == "assistant"
+        raise ArgumentError, "LLM usage must be LLMAdapter::TokenUsage" unless usage.is_a?(Phronomy::LLMAdapter::TokenUsage)
+        @usage = usage
+        super(role: :assistant, content: content, tool_calls: tool_calls, metadata: metadata)
+      end
+
+      # @api public
+      def self.from_h(value)
+        source = value.transform_keys(&:to_s)
+        new(role: source.fetch("role", "assistant"), content: source["content"],
+          tool_calls: source.fetch("tool_calls", []).map { |call| Phronomy::Tool::CallRequest.from_h(call) },
+          usage: Phronomy::LLMAdapter::TokenUsage.new(**source.fetch("usage", {}).transform_keys(&:to_sym)),
+          metadata: source.fetch("metadata", {}))
+      end
+
+      # @api public
+      def to_h
+        super.merge("usage" => usage.to_h.transform_keys(&:to_s))
+      end
+    end
+  end
+end

data/lib/phronomy/llm_adapter/stream_chunk.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module LLMAdapter
+    # Intermediate text notification; the final Response is authoritative.
+    # @api public
+    class StreamChunk
+      attr_reader :content
+
+      # @api public
+      def initialize(content:)
+        raise ArgumentError, "stream content must be a String or nil" unless content.nil? || content.is_a?(String)
+        @content = content&.dup&.freeze
+        freeze
+      end
+    end
+  end
+end