phronomy 0.27.0 → 0.29.0

data/lib/phronomy/generation/generator_verifier/agent_operation.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class GeneratorVerifier
+    # Connects one reused Agent incarnation through its public operation and
+    # notification contracts. Terminal results belong to each returned TaskResult;
+    # only approval suspension needs the incarnation listener while that Task is
+    # still pending. Generation owns the request-to-Workflow correlation.
+    # @api private
+    class AgentOperation
+      def initialize(agent_class)
+        @mutex = Mutex.new
+        @pending = []
+        @agent = agent_class.new(on_event: method(:receive_event))
+      end
+
+      def start(input, listener:)
+        request = Object.new
+        # Workflow entry calls are serial. Keep submitted requests until their
+        # own result settles: Agent admission itself may run after an earlier
+        # request completes, so a pending submission is not necessarily busy.
+        @mutex.synchronize { @pending << [request, listener] }
+        task = @agent.invoke_async(input)
+        task.on_complete do |result, error|
+          release(request)
+          # Handoff was not a generation completion in the event-based path.
+          next if !error && result.is_a?(Hash) && result[:handoff_request]
+
+          event = if error
+            type = if error.is_a?(Phronomy::TimeoutError)
+              :timeout
+            elsif error.is_a?(Phronomy::CancellationError)
+              :cancelled
+            else
+              :error
+            end
+            Phronomy::Agent::StreamEvent.new(type: type, payload: {error: error})
+          else
+            Phronomy::Agent::StreamEvent.new(type: :done, payload: result)
+          end
+          listener.call(event)
+        end
+        task
+      rescue
+        release(request)
+        raise
+      end
+
+      private
+
+      def receive_event(event)
+        return unless event.type == :approval_required
+
+        listener = @mutex.synchronize { @pending.first&.last }
+        listener&.call(event)
+      end
+
+      def release(request)
+        @mutex.synchronize do
+          @pending.delete_if { |entry| entry.first.equal?(request) }
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/generation/generator_verifier/default_parser.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class GeneratorVerifier
+    # Boot supplies the default concrete parser. The generation algorithm owns
+    # its output interpretation and fallback, not the concrete parser selection.
+    # @api private
+    module DefaultParser
+      FACTORIES = {}
+      private_constant :FACTORIES
+
+      # Private one-time composition binding; not an application registry.
+      # @api private
+      def self.install_factory(factory)
+        raise ArgumentError, "factory must respond to call" unless factory.respond_to?(:call)
+
+        FACTORIES.replace(parser: factory).freeze
+        nil
+      end
+
+      # @api private
+      def self.build
+        FACTORIES.fetch(:parser).call
+      end
+    end
+  end
+end

data/lib/phronomy/generation/generator_verifier/workflow_builder.rb

@@ -71,7 +71,7 @@ module Phronomy
           workflow_instance_id: next_state.workflow_instance_id,
           request_id: request_id
         )
-        @draft_agent.send(:__invoke_async_with_event_sink, prompt, on_event: listener)
+        @draft_agent.start(prompt, listener: listener)
         next_state
       end
 
@@ -86,7 +86,7 @@ module Phronomy
           workflow_instance_id: next_state.workflow_instance_id,
           request_id: request_id
         )
-        @review_agent.send(:__invoke_async_with_event_sink, prompt, on_event: listener)
+        @review_agent.start(prompt, listener: listener)
         next_state
       end
 

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/generation/low_confidence_error.rb

@@ -6,9 +6,9 @@ module Phronomy
   class LowConfidenceError < Error
     attr_reader :result
 
-    def initialize(result)
+    def initialize(result, code: nil)
       @result = result
-      super("Answer confidence #{result.confidence} is below the required threshold")
+      super("Answer confidence #{result.confidence} is below the required threshold", code: code)
     end
   end
 end

data/lib/phronomy/integrations/ordered_event_delivery.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require_relative "../common/error"
+
+module Phronomy
+  module Integrations
+    # Optional transport helper. Payload meaning and destinations belong to the app.
+    # @api public
+    class OrderedEventDelivery
+      class ClosedError < Phronomy::Error; end
+      class OverflowError < Phronomy::Error; end
+
+      # Close and drain after the block, preserving its result or original failure.
+      # A flush timeout limits waiting, not an in-flight network request.
+      # @api public
+      def self.open(deliver:, capacity: 256, batch_size: 32, flush_timeout: 30, prepare_batch: nil)
+        raise ArgumentError, "block required" unless block_given?
+        reject_event_loop!
+        validate_timeout!(flush_timeout)
+        raise ArgumentError, "deliver must be callable" unless deliver.respond_to?(:call)
+        delivery = new(capacity: capacity, batch_size: batch_size, prepare_batch: prepare_batch, &deliver)
+        begin
+          yield delivery
+        ensure
+          primary = $!
+          begin
+            delivery.close_and_wait(timeout: flush_timeout)
+          rescue => secondary
+            if primary
+              report_secondary(secondary)
+            else
+              raise
+            end
+          end
+        end
+      end
+
+      def self.reject_event_loop!
+        if Phronomy::Runtime.in_event_loop_context?
+          raise Phronomy::EventLoopReentrancyError, "delivery flush cannot block EventLoop"
+        end
+      end
+
+      def self.validate_timeout!(timeout)
+        valid = timeout.nil? || (timeout.is_a?(Numeric) && timeout.finite? && timeout >= 0)
+        raise ArgumentError, "flush timeout must be a finite nonnegative number or nil" unless valid
+      end
+
+      def self.report_secondary(error)
+        Phronomy.configuration.logger&.error("[OrderedEventDelivery] secondary delivery failure: #{error.class}: #{error.message}")
+      rescue
+        # Diagnostic reporting must not replace the primary application error.
+        nil
+      end
+      private_class_method :reject_event_loop!, :validate_timeout!, :report_secondary
+
+      # Construction does not start a worker or create a pool.
+      # @api public
+      def initialize(capacity: 256, batch_size: 32, prepare_batch: nil, &deliver)
+        raise ArgumentError, "deliver block required" unless deliver
+        unless capacity.is_a?(Integer) && capacity.positive? && batch_size.is_a?(Integer) && batch_size.positive?
+          raise ArgumentError, "capacity and batch_size must be positive Integers"
+        end
+        raise ArgumentError, "prepare_batch must be callable" if prepare_batch && !prepare_batch.respond_to?(:call)
+        @capacity, @batch_size = capacity, batch_size
+        @prepare_batch, @deliver = prepare_batch, deliver
+        @mutex = Mutex.new
+        @condition = ConditionVariable.new
+        @queue = []
+        @accepting = true
+        @worker = nil
+        @failure = nil
+      end
+
+      # Snapshot plain data; admission order is the queue insertion order.
+      # Capacity counts queued payloads, excluding the active batch.
+      # @api public
+      def publish(payload)
+        value = immutable_copy(payload)
+        ticket = @mutex.synchronize do
+          raise @failure if @failure
+          raise ClosedError.new("event delivery closed", code: "delivery.closed") unless @accepting
+          raise OverflowError.new("event delivery queue full", code: "delivery.capacity_exceeded") if @queue.length >= @capacity
+          @queue << value
+          next nil if @worker
+          @worker = {started: false}
+        end
+        start_drain(ticket) if ticket
+        error = @mutex.synchronize { @failure }
+        raise error if error
+        self
+      rescue => error
+        # Listener dispatch can log an exception and continue. Retain the failure
+        # for close while continuing to drain already accepted work if possible.
+        @mutex.synchronize do
+          @failure ||= error
+          @accepting = false
+        end
+        raise
+      end
+
+      # External callers only. Concurrent close calls observe the same drain.
+      # Timeout does not abort a network operation or settle the worker's result.
+      # @api public
+      def close_and_wait(timeout: nil)
+        self.class.send(:reject_event_loop!)
+        self.class.send(:validate_timeout!, timeout)
+        deadline = timeout && monotonic_now + timeout
+        @mutex.synchronize do
+          @accepting = false
+          while @worker
+            remaining = deadline && deadline - monotonic_now
+            raise Phronomy::TimeoutError, "event delivery flush timed out" if remaining && remaining <= 0
+            @condition.wait(@mutex, remaining)
+          end
+          raise @failure if @failure
+        end
+        self
+      end
+
+      private
+
+      def start_drain(ticket)
+        Phronomy::Blocking.call_async do
+          started = @mutex.synchronize do
+            ticket[:started] = true if @worker.equal?(ticket)
+          end
+          if started
+            begin
+              drain(ticket)
+            rescue => error
+              fail_worker(ticket, error)
+            ensure
+              finish_worker(ticket)
+            end
+          end
+        end.on_complete do |_value, error|
+          fail_worker(ticket, error) if error
+        end
+      rescue => error
+        fail_worker(ticket, error)
+      end
+
+      def drain(ticket)
+        loop do
+          batch = @mutex.synchronize do
+            if @queue.empty?
+              # Publish must observe queue emptiness and ownership release together.
+              release_worker(ticket)
+              nil
+            else
+              @queue.shift(@batch_size)
+            end
+          end
+          return unless batch
+          prepared = @prepare_batch ? @prepare_batch.call(batch.freeze) : batch
+          raise ArgumentError, "prepare_batch must return an Array" unless prepared.is_a?(Array)
+          immutable_copy(prepared).each { |payload| @deliver.call(payload) }
+        end
+      end
+
+      def fail_worker(ticket, error)
+        @mutex.synchronize do
+          @failure ||= error
+          @accepting = false
+          @queue.clear
+          # Logical cancellation can precede physical worker exit. Keep waiting
+          # for a started delivery; never mistake settled TaskResult for exit.
+          release_worker(ticket) unless ticket[:started]
+        end
+      end
+
+      def finish_worker(ticket)
+        @mutex.synchronize { release_worker(ticket) }
+      end
+
+      def release_worker(ticket)
+        return unless @worker.equal?(ticket)
+        @worker = nil
+        @condition.broadcast
+      end
+
+      def immutable_copy(value, ancestors = {})
+        case value
+        when Hash, Array
+          raise ArgumentError, "event payload must contain acyclic plain data" if ancestors[value.object_id]
+          path = ancestors.merge(value.object_id => true)
+          if value.is_a?(Hash)
+            value.to_h { |key, child| [immutable_copy(key, path), immutable_copy(child, path)] }.freeze
+          else
+            value.map { |child| immutable_copy(child, path) }.freeze
+          end
+        when String then value.dup.freeze
+        when Integer, Symbol, TrueClass, FalseClass, NilClass then value
+        when Float
+          raise ArgumentError, "event payload numbers must be finite" unless value.finite?
+          value
+        else
+          raise ArgumentError, "event payload must contain plain data: #{value.class}"
+        end
+      end
+
+      def monotonic_now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    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