phronomy 0.27.0 → 0.29.0

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

data/lib/phronomy/llm_adapter/token_usage.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module LLMAdapter
+    # Immutable usage counts. An omitted count remains nil; zero is a reported
+    # measurement. SDK field translation belongs to the backend.
+    # @api public
+    class TokenUsage
+      attr_reader :input, :output, :cached, :cache_creation
+
+      def initialize(input: nil, output: nil, cached: nil, cache_creation: nil)
+        [input, output, cached, cache_creation].each do |value|
+          if !(value.nil? || (value.is_a?(Integer) && value >= 0))
+            raise ArgumentError, "token usage must be non-negative Integers or nil"
+          end
+        end
+        @input = input
+        @output = output
+        @cached = cached
+        @cache_creation = cache_creation
+        freeze
+      end
+
+      # Returns a zero-valued TokenUsage suitable as an accumulator seed.
+      def self.zero
+        new(input: 0, output: 0, cached: 0, cache_creation: 0)
+      end
+
+      # Adds two TokenUsage instances. nil fields are treated as 0 so that
+      # partially-reported usage accumulates correctly.
+      # When other is nil, returns self unchanged.
+      def +(other)
+        return self if other.nil?
+
+        self.class.new(
+          input: _add(input, other.input),
+          output: _add(output, other.output),
+          cached: _add(cached, other.cached),
+          cache_creation: _add(cache_creation, other.cache_creation)
+        )
+      end
+
+      def ==(other)
+        other.is_a?(TokenUsage) &&
+          input == other.input &&
+          output == other.output &&
+          cached == other.cached &&
+          cache_creation == other.cache_creation
+      end
+
+      def to_h
+        {input: input, output: output, cached: cached, cache_creation: cache_creation}
+      end
+
+      private
+
+      def _add(a, b)
+        return nil if a.nil? && b.nil?
+
+        (a || 0) + (b || 0)
+      end
+    end
+  end
+end

data/lib/phronomy/llm_adapter/transport_error.rb

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

data/lib/phronomy/llm_adapter.rb

@@ -1,22 +1,9 @@
 # frozen_string_literal: true
 
 module Phronomy
-  # Namespace for LLM call adapters.
-  #
-  # The public extension boundary is {LLMAdapter::Base#complete} and
-  # {LLMAdapter::Base#stream}. Those methods receive Phronomy's currently
-  # materialized chat/runtime object and perform the provider call. Phronomy owns
-  # the async/offload bridge around that synchronous contract.
-  #
-  # This SPI does not by itself make the complete input-materialization pipeline
-  # provider-neutral: the current Agent pipeline still materializes the canonical
-  # LLM input through RubyLLM-specific runtime objects before invoking the adapter.
-  #
-  # @example Configuring a custom adapter
-  #   Phronomy.configure do |c|
-  #     c.llm_adapter = MyCustomAdapter.new
-  #   end
-  #
+  # LLM domain operations and public request, response, usage and failure values.
+  # A backend implements Base's protected hooks. SDK objects remain inside the
+  # backend; AsyncClient executes the entire synchronous operation on a worker.
   # @api public
   module LLMAdapter
   end

data/lib/phronomy/multi_agent/admission_registry.rb

@@ -2,18 +2,11 @@
 
 module Phronomy
   module MultiAgent
-    # Runtime-local admission for one synchronous coordination call per owner
+    # Environment-local admission for one synchronous coordination call per owner
     # (a Handoff main Agent or TeamCoordinator). This does not own durable runs
     # or active-agent mutation; those remain in their existing domains.
     # @api private
     class AdmissionRegistry
-      # Construction has no side effects. Runtime returns the registered instance
-      # when callers concurrently supply candidates for the same key.
-      # @api private
-      def self.for(runtime)
-        runtime.__register_shutdown_participant(key: self, participant: new)
-      end
-
       def initialize
         @mutex = Mutex.new
         @cond = ConditionVariable.new