phronomy 0.26.0 → 0.28.0

data/lib/phronomy/generation/generator_verifier.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Implements the Generator-Verifier multi-agent coordination pattern.
+  #
+  # Agent completion is integrated through application-defined Workflow events;
+  # Workflow entry actions do not return or await Agent Tasks.
+  class GeneratorVerifier
+    DEFAULT_CONFIDENCE_THRESHOLD = 0.7
+    DEFAULT_MAX_ITERATIONS = 3
+
+    Result = Struct.new(
+      :output,
+      :confidence,
+      :citations,
+      :iterations,
+      :review_notes,
+      :trusted
+    ) do
+      alias_method :trusted?, :trusted
+    end
+
+    private_constant :PipelineState, :WorkflowBuilder, :AgentResultReceiver, :AgentOperation
+
+    def initialize(
+      draft_agent:,
+      review_agent:,
+      draft_prompt_builder:,
+      review_prompt_builder:,
+      draft_result_parser: nil,
+      review_result_parser: nil,
+      confidence_threshold: DEFAULT_CONFIDENCE_THRESHOLD,
+      max_iterations: DEFAULT_MAX_ITERATIONS,
+      raise_if_untrusted: false
+    )
+      @draft_agent_class = draft_agent
+      @review_agent_class = review_agent
+      @draft_prompt_builder = draft_prompt_builder
+      @review_prompt_builder = review_prompt_builder
+      @draft_result_parser =
+        draft_result_parser || method(:default_parse_draft)
+      @review_result_parser =
+        review_result_parser || method(:default_parse_review)
+      @threshold = confidence_threshold.to_f
+      @max_iterations = max_iterations.to_i
+      @raise_if_untrusted = raise_if_untrusted
+      @compiled_workflow = nil
+    end
+
+    def invoke(input, config: {})
+      state = compiled_workflow.invoke({input: input}, config: config)
+      confidence = combined_confidence(state)
+      trusted = confidence >= @threshold
+      result = Result.new(
+        output: state.output || state.draft.to_s,
+        confidence: confidence,
+        citations: state.citations,
+        iterations: state.iteration,
+        review_notes: state.review_notes,
+        trusted: trusted
+      )
+      if @raise_if_untrusted && !trusted
+        raise LowConfidenceError.new(result)
+      end
+      result
+    end
+
+    private
+
+    def combined_confidence(state)
+      [
+        (state.self_score || 0.0).to_f,
+        (state.review_score || 0.0).to_f
+      ].min
+    end
+
+    def compiled_workflow
+      @compiled_workflow ||= build_workflow
+    end
+
+    def build_workflow
+      WorkflowBuilder.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,
+        review_result_parser: @review_result_parser,
+        threshold: @threshold,
+        max_iterations: @max_iterations
+      ).build
+    end
+
+    def default_parse_draft(text)
+      default_parser.parse(text)
+    rescue Phronomy::ParseError
+      {
+        answer: text.to_s,
+        confidence: 0.0,
+        citations: []
+      }
+    end
+
+    def default_parse_review(text)
+      default_parser.parse(text)
+    rescue Phronomy::ParseError
+      {
+        approved: false,
+        score: 0.0,
+        feedback: "Review output could not be parsed: #{text}"
+      }
+    end
+
+    def default_parser
+      @default_parser ||= DefaultParser.build
+    end
+  end
+end

data/lib/phronomy/generation/low_confidence_error.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "../common/error"
+
+module Phronomy
+  class LowConfidenceError < Error
+    attr_reader :result
+
+    def initialize(result)
+      @result = result
+      super("Answer confidence #{result.confidence} is below the required threshold")
+    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_adapter/authentication_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "transport_error"
+
+module Phronomy
+  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_adapter/context_length_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "../common/error"
+
+module Phronomy
+  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_adapter/rate_limit_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "transport_error"
+
+module Phronomy
+  module LLMAdapter
+    class RateLimitError < TransportError; end
+  end
+end