phronomy 0.26.0 → 0.28.0

data/lib/phronomy/embeddings/backends/ruby_llm_embeddings.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Embeddings
+    # Embeddings adapter backed by RubyLLM.
+    #
+    # Delegates to +RubyLLM.embed+ and returns the resulting vector as an
+    # +Array<Float>+.
+    #
+    # @example Default model
+    #   embeddings = Phronomy::Embeddings::RubyLLMEmbeddings.new
+    #   vector = embeddings.embed("Hello, world!")
+    #
+    # @example Explicit model
+    #   embeddings = Phronomy::Embeddings::RubyLLMEmbeddings.new(model: "text-embedding-3-small")
+    #   vector = embeddings.embed("Hello, world!")
+    class RubyLLMEmbeddings < Base
+      # @param model               [String, nil] embedding model identifier; nil uses the RubyLLM default
+      # @param provider            [Symbol, nil] provider override (e.g. :openai); nil uses the RubyLLM default
+      # @param assume_model_exists [Boolean]     when true, skips RubyLLM model-registry validation
+      #                                          (useful for locally hosted models not in the registry)
+      # @api public
+      def initialize(model: nil, provider: nil, assume_model_exists: false)
+        @model = model
+        @provider = provider
+        @assume_model_exists = assume_model_exists
+      end
+
+      protected
+
+      # Embed text via RubyLLM.
+      #
+      # @param text               [String]
+      # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil] optional; raises CancellationError when cancelled
+      # @return [Array<Float>]
+      # @api public
+      def perform_embed(text, cancellation_token = nil)
+        opts = {}
+        opts[:model] = @model if @model
+        opts[:provider] = @provider if @provider
+        opts[:assume_model_exists] = true if @assume_model_exists
+        ::RubyLLM.embed(text, **opts).vectors
+      rescue ::RubyLLM::Error => error
+        raise TransportError, error.message
+      end
+    end
+  end
+end

data/lib/phronomy/embeddings/base.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "invalid_result_error"
+
+module Phronomy
+  module Embeddings
+    # Owns input validation, the cancellation checkpoint and result validation.
+    # Providers implement perform_embed; execution belongs to AsyncClient.
+    # This contract selects no provider or vector store.
+    # @api public
+    class Base
+      # @param text [String] empty text is allowed; model restrictions are provider-owned
+      # @param cancellation_token [#raise_if_cancelled!, nil]
+      # @return [Array<Float>] non-empty finite vector
+      # @raise [ArgumentError] when input is not text
+      # @raise [InvalidResultError] when the provider returns a malformed vector
+      # @api public
+      def embed(text, cancellation_token = nil)
+        cancellation_token&.raise_if_cancelled!
+        raise ArgumentError, "text must be a String" unless text.is_a?(String)
+        vector = perform_embed(text, cancellation_token)
+        unless vector.is_a?(Array) && !vector.empty? && vector.all? { |value|
+          value.is_a?(Numeric) && value.real? && value.finite? && value.to_f.finite?
+        }
+          raise InvalidResultError, "embed must return a non-empty Array of finite real numbers"
+        end
+        vector.map(&:to_f)
+      end
+
+      protected
+
+      # Provider extension point. Preserve cancellation and application errors;
+      # SDK adapters translate their own provider errors to TransportError.
+      # @param text [String]
+      # @param cancellation_token [#raise_if_cancelled!, nil]
+      # @return [Array<Numeric>]
+      # @api public
+      def perform_embed(text, cancellation_token = nil)
+        raise NotImplementedError, "#{self.class}#perform_embed is not implemented"
+      end
+    end
+  end
+end

data/lib/phronomy/embeddings/invalid_result_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "../common/error"
+
+module Phronomy
+  module Embeddings
+    # A provider returned data that violates the embedding result contract.
+    # @api public
+    class InvalidResultError < Phronomy::Error; end
+  end
+end

data/lib/phronomy/embeddings/transport_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "../common/error"
+
+module Phronomy
+  module Embeddings
+    # An embedding provider failed; the original SDK exception remains #cause.
+    # @api public
+    class TransportError < Phronomy::Error; end
+  end
+end

data/lib/phronomy/engine/concurrency/offload_pool.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../../execution/concurrency/worker_input_restricted"
+
 module Phronomy
   module Concurrency
     # A bounded, observable thread pool for synchronous work that must not run on
@@ -41,6 +43,8 @@ module Phronomy
     #   task = pool.submit(timeout: 30, cancellation_token: token) { expensive_call }
     #   result = task.wait_result
     class OffloadPool
+      include Phronomy::Concurrency::WorkerInputRestricted
+
       # Private execution record for one submitted synchronous operation.
       #
       # Caller-facing completion is represented exclusively by {Phronomy::TaskResult}.
@@ -77,14 +81,12 @@ module Phronomy
           @submitted_at = submitted_at ||
             Process.clock_gettime(Process::CLOCK_MONOTONIC)
           @mutex = Mutex.new
-          @timer_subscriptions = Subscriptions.new
+          @timer_subscriptions = ResultSubscriptions.new
+          @cancellation_subscriptions = ResultSubscriptions.new
 
           # Explicit submit cancellation is operation-wide. Deadline-only tokens are
           # promoted to cancel! by OffloadPool#submit using the Runtime timer queue.
-          @cancellation_callback = if @cancellation_token
-            -> { fire_cancellation! }
-          end
-          @cancellation_token&.on_cancel(&@cancellation_callback)
+          @cancellation_subscriptions.explicit_cancellation(@cancellation_token) { fire_cancellation! }
         end
 
         # @return [Boolean] true when caller-facing settlement has been claimed
@@ -256,7 +258,7 @@ module Phronomy
         def notify_abandoned
           @on_abandoned&.call(self)
         rescue => error
-          Phronomy.configuration.logger&.error do
+          Phronomy::RuntimeSettings.current.logger&.error do
             "OffloadPool abandoned callback failed: #{error.class}: #{error.message}"
           end
         end
@@ -289,13 +291,7 @@ module Phronomy
 
         def detach_submit_cancellation
           @timer_subscriptions.close
-          return unless @cancellation_token && @cancellation_callback
-
-          @cancellation_token.send(
-            :unregister_cancel_callback,
-            @cancellation_callback
-          )
-          @cancellation_callback = nil
+          @cancellation_subscriptions.close
         end
       end
       private_constant :Operation
@@ -380,7 +376,7 @@ module Phronomy
         full_timeout: nil,
         &block
       )
-        if Phronomy::Runtime.in_event_loop_context? && on_full != :raise
+        if Phronomy::WaitPolicy.blocking_forbidden? && on_full != :raise
           raise Phronomy::EventLoopReentrancyError,
             "OffloadPool admission cannot wait on EventLoop; use on_full: :raise"
         end
@@ -487,19 +483,42 @@ module Phronomy
         task
       end
 
-      # Gracefully drains the pool and terminates all worker threads.
-      # Waits up to +drain_timeout+ seconds for in-flight operations to finish.
+      # Close admission without waiting for worker termination. Already queued
+      # operations drain normally; running workers are never interrupted.
+      # @api private
+      def begin_shutdown
+        @shutdown = true
+        @queue.close
+        self
+      end
+
+      # Whether shutdown has closed admission and all workers have exited.
+      # Logical TaskResult settlement alone does not establish this fact.
+      # @api private
+      def terminated?
+        @shutdown && @workers.none?(&:alive?)
+      end
+
+      # Gracefully drains the pool and waits for worker threads to terminate.
+      # All workers share +drain_timeout+ or the supplied monotonic +deadline+.
+      # A deadline expiry leaves workers running; callers inspect terminated?.
       #
       # Closing the underlying SizedQueue signals workers to exit after draining
       # remaining items, without blocking on a full-queue push.
       #
       # @param drain_timeout [Numeric] seconds to wait for workers to finish
+      # @param deadline [Numeric, nil] absolute monotonic shutdown deadline
       # @return [self]
       # @api private
-      def shutdown(drain_timeout: 30)
-        @shutdown = true
-        @queue.close
-        @workers.each { |thread| thread.join(drain_timeout) }
+      def shutdown(drain_timeout: 30, deadline: nil)
+        deadline ||= Process.clock_gettime(Process::CLOCK_MONOTONIC) + drain_timeout
+        begin_shutdown
+        @workers.each do |thread|
+          remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          break if remaining <= 0
+
+          thread.join(remaining)
+        end
         self
       end
 

data/lib/phronomy/engine/concurrency/pool_registry.rb

@@ -16,6 +16,7 @@ module Phronomy
         @mutex = Mutex.new
         @pools = {}
         @default = nil
+        @closed = false
       end
 
       # Returns (or lazily creates) the unnamed default pool.
@@ -24,12 +25,22 @@ module Phronomy
       # @return [OffloadPool]
       # @api private
       def default_pool(pool_size: 10, queue_size: 100)
-        @default ||= OffloadPool.new(
-          name: :default,
-          pool_size: pool_size,
-          queue_size: queue_size,
-          timer_queue_provider: @timer_queue_provider
-        )
+        @mutex.synchronize do
+          ensure_open!
+          @default ||= OffloadPool.new(
+            name: :default,
+            pool_size: pool_size,
+            queue_size: queue_size,
+            timer_queue_provider: @timer_queue_provider
+          )
+        end
+      end
+
+      # Lookup only, including after registration has closed.
+      # @return [OffloadPool, nil]
+      # @api private
+      def default_pool_if_initialized
+        @mutex.synchronize { @default }
       end
 
       # Returns (or lazily creates) a named pool.
@@ -40,6 +51,7 @@ module Phronomy
       # @api private
       def named_pool(name, size: 10, queue_size: 100)
         @mutex.synchronize do
+          ensure_open!
           @pools[name.to_sym] ||= OffloadPool.new(
             name: name,
             pool_size: size,
@@ -49,13 +61,36 @@ module Phronomy
         end
       end
 
-      # Shuts down the default pool and all named pools.
-      # @return [void]
+      # Closes registration and every pool before waiting, outside the registry
+      # lock. All pools share one absolute monotonic deadline. Attempt every
+      # cleanup even if one fails; report physical completion separately.
+      # @return [Boolean] whether every owned worker has stopped
       # @api private
-      def shutdown
-        @default&.shutdown
-        pools = @mutex.synchronize { @pools.values.dup }
-        pools.each(&:shutdown)
+      def shutdown(deadline: Process.clock_gettime(Process::CLOCK_MONOTONIC) + 30)
+        pools = @mutex.synchronize do
+          @closed = true
+          [@default, *@pools.values].compact
+        end
+        error = nil
+        pools.each do |pool|
+          pool.begin_shutdown
+        rescue => caught
+          error ||= caught
+        end
+        pools.each do |pool|
+          pool.shutdown(deadline: deadline)
+        rescue => caught
+          error ||= caught
+        end
+        raise error if error
+
+        pools.all?(&:terminated?)
+      end
+
+      private
+
+      def ensure_open!
+        raise Phronomy::PoolShutdownError, "pool registry has been shut down" if @closed
       end
     end
   end

data/lib/phronomy/{diagnostics.rb → engine/diagnostics.rb}

@@ -24,7 +24,7 @@ module Phronomy
     end
 
     def self.assert_not_in_event_loop!
-      return unless Phronomy::Runtime.in_event_loop_context?
+      return unless Phronomy::WaitPolicy.blocking_forbidden?
 
       raise Phronomy::EventLoopReentrancyError,
         "Blocking invoke called from inside an EventLoop action. Use invoke_async instead."