phronomy 0.7.1 → 0.8.0

data/lib/phronomy/concurrency_gate.rb

@@ -1,155 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  # A counting semaphore that enforces a concurrency cap across a named
-  # resource category (e.g. agent tasks, tool tasks, LLM calls).
-  #
-  # When +max_concurrent+ is +nil+ the gate is a no-op and all callers
-  # pass through immediately without acquiring a slot.
-  #
-  # Backpressure behaviour when the gate is full is controlled by the
-  # +on_full:+ keyword:
-  #   +:reject+  — raise {Phronomy::BackpressureError} immediately
-  #   +:wait+    — block the calling fiber/thread until a slot is free
-  #   +:timeout+ — like +:wait+ but raises {Phronomy::BackpressureError}
-  #               after +timeout:+ seconds if no slot becomes available
-  #
-  # @example
-  #   gate = Phronomy::ConcurrencyGate.new(max_concurrent: 5, name: :agent)
-  #   gate.acquire(on_full: :reject) do
-  #     run_agent_task
-  #   end
-  class ConcurrencyGate
-    # @param max_concurrent [Integer, nil] concurrency cap; nil = unlimited
-    # @param name [Symbol, String, nil] human-readable label used in error messages
-    # @api private
-    def initialize(max_concurrent:, name: nil)
-      @max = max_concurrent
-      @name = name
-      @mutex = Mutex.new
-      @cond = ConditionVariable.new
-      @count = 0
-    end
-
-    # Returns the configured cap (or nil when unlimited).
-    attr_reader :max
-
-    # Returns the name label.
-    attr_reader :name
-
-    # Returns the number of slots currently in use.
-    def current_count
-      @mutex.synchronize { @count }
-    end
-
-    # Acquires a slot, executes +block+, then releases the slot.
-    # When the gate is unlimited (max is nil) the block runs directly.
-    #
-    # @param on_full [:reject, :wait, :timeout] backpressure strategy
-    # @param timeout [Numeric, nil] seconds before +:timeout+ gives up
-    # @yield
-    # @return block return value
-    # @raise [Phronomy::BackpressureError] when +:reject+ or +:timeout+ fires
-    # @api private
-    def acquire(on_full: :wait, timeout: nil, &block)
-      return block.call if @max.nil?
-
-      _acquire_slot(on_full: on_full, timeout: timeout)
-      begin
-        block.call
-      ensure
-        _release_slot
-      end
-    end
-
-    private
-
-    def _acquire_slot(on_full:, timeout:)
-      scheduler = Phronomy::Runtime::Scheduler.current
-      if scheduler
-        _acquire_slot_coop(scheduler, on_full: on_full, timeout: timeout)
-      else
-        _acquire_slot_threaded(on_full: on_full, timeout: timeout)
-      end
-    end
-
-    def _acquire_slot_coop(scheduler, on_full:, timeout:)
-      # In cooperative mode all tasks run on the same thread, so no mutex needed.
-      deadline = timeout ? (scheduler.virtual_time + timeout) : nil
-      @coop_signal ||= scheduler.new_signal
-
-      loop do
-        if @count < @max
-          @count += 1
-          return
-        end
-
-        case on_full
-        when :reject
-          raise Phronomy::BackpressureError,
-            "ConcurrencyGate[#{@name}] at capacity (#{@max}); " \
-            "increase max_concurrent_#{@name}_tasks or retry later"
-        when :timeout
-          if deadline && scheduler.virtual_time >= deadline
-            raise Phronomy::BackpressureError,
-              "ConcurrencyGate[#{@name}] timed out waiting for a free slot (cap: #{@max})"
-          end
-          scheduler.wait_for_signal(@coop_signal)
-          if deadline && scheduler.virtual_time >= deadline
-            raise Phronomy::BackpressureError,
-              "ConcurrencyGate[#{@name}] timed out waiting for a free slot (cap: #{@max})"
-          end
-        else # :wait
-          scheduler.wait_for_signal(@coop_signal)
-        end
-      end
-    end
-
-    def _acquire_slot_threaded(on_full:, timeout:)
-      deadline = timeout ? (Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout) : nil
-
-      @mutex.synchronize do
-        loop do
-          if @count < @max
-            @count += 1
-            return
-          end
-
-          case on_full
-          when :reject
-            raise Phronomy::BackpressureError,
-              "ConcurrencyGate[#{@name}] at capacity (#{@max}); " \
-              "increase max_concurrent_#{@name}_tasks or retry later"
-          when :timeout
-            remaining = deadline ? (deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)) : nil
-            if remaining && remaining <= 0
-              raise Phronomy::BackpressureError,
-                "ConcurrencyGate[#{@name}] timed out waiting for a free slot (cap: #{@max})"
-            end
-            @cond.wait(@mutex, remaining || nil)
-            # re-check deadline after wakeup
-            if deadline && Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
-              raise Phronomy::BackpressureError,
-                "ConcurrencyGate[#{@name}] timed out waiting for a free slot (cap: #{@max})"
-            end
-          else # :wait
-            @cond.wait(@mutex)
-          end
-        end
-      end
-    end
-
-    def _release_slot
-      scheduler = Phronomy::Runtime::Scheduler.current
-      if scheduler && @coop_signal
-        @count -= 1
-        scheduler.raise_signal(@coop_signal)
-      else
-        @mutex.synchronize do
-          @count -= 1
-          @cond.signal
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/context/compaction_context.rb

@@ -1,111 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Context
-    # Context object passed to the +on_compact+ callback registered on an agent.
-    #
-    # The callback calls #compact one or more times to specify which ranges of
-    # messages to replace with a summary. Each call:
-    #   1. Yields the selected message elements to the block.
-    #   2. Receives the block's return value as the summary text.
-    #   3. Persists a compaction record to the memory store (if available).
-    #   4. Updates #result_messages so that the compacted range is replaced
-    #      by a single +:system+ summary message.
-    #
-    # The agent reads #result_messages after the callback returns and uses it
-    # as the new message list for this invocation.
-    #
-    # @example Summarise the oldest half of the conversation
-    #   on_compact do |ctx|
-    #     half = ctx.message_elements.length / 2
-    #     ctx.compact(0...half) do |elements|
-    #       texts = elements.map { |e| "#{e[:role]}: #{e[:message].content}" }.join("\n")
-    #       "Summary of earlier conversation:\n#{texts}"
-    #     end
-    #   end
-    class CompactionContext
-      # @return [Array<Hash>] message elements at compaction time
-      attr_reader :message_elements
-
-      # @return [Phronomy::Context::TokenBudget, nil]
-      attr_reader :budget
-
-      # @return [Integer] total estimated token count before compaction
-      attr_reader :total_tokens
-
-      # The current message list to be used after all compact calls have been made.
-      # Updated by each call to #compact.
-      #
-      # @return [Array]
-      attr_reader :result_messages
-
-      # @param message_elements [Array<Hash>]
-      #   each element: { seq: Integer, message: Object, tokens: Integer, role: Symbol }
-      # @param budget [Phronomy::Context::TokenBudget, nil]
-      # @param thread_id [String, nil] used when saving compaction records
-      # @param memory [Object, nil] memory object; must respond to #save_compaction
-      #   for compaction records to be persisted
-      # @api private
-      def initialize(message_elements:, budget:, thread_id: nil, memory: nil)
-        @message_elements = message_elements.dup
-        @budget = budget
-        @total_tokens = message_elements.sum { |e| e[:tokens] }
-        @thread_id = thread_id
-        @memory = memory
-        @result_messages = @message_elements.map { |e| e[:message] }
-      end
-
-      # Replace a range of messages with a summary produced by the block.
-      #
-      # The block receives the selected Array<Hash> elements and must return a
-      # String that serves as the summary text. After the call, #result_messages
-      # reflects the replacement.
-      #
-      # If the memory object responds to #save_compaction, a compaction record
-      # { start_seq:, end_seq:, summary_text: } is persisted for auditability.
-      #
-      # @param range [Range, Integer] index range into message_elements (0-based)
-      # @yieldparam elements [Array<Hash>] the selected message elements
-      # @yieldreturn [String] summary text to replace the selected messages
-      # @return [Array] the updated result_messages array
-      # @api private
-      def compact(range)
-        # Normalise: Integer index → single-element Array; Range → Array slice.
-        raw = @message_elements[range]
-        elements = if raw.is_a?(Array)
-          raw
-        elsif raw.nil?
-          []
-        else
-          [raw]
-        end
-        return @result_messages if elements.empty?
-
-        summary_text = yield(elements).to_s
-
-        start_seq = elements.first[:seq]
-        end_seq = elements.last[:seq]
-
-        if @memory && @thread_id && @memory.respond_to?(:save_compaction)
-          @memory.save_compaction(
-            thread_id: @thread_id,
-            start_seq: start_seq,
-            end_seq: end_seq,
-            summary_text: summary_text
-          )
-        end
-
-        # Compute the last included index in the original @message_elements array.
-        last_idx = if range.is_a?(Range)
-          range.exclude_end? ? range.last - 1 : range.last
-        else
-          range.to_i
-        end
-
-        remaining = (@message_elements[(last_idx + 1)..] || []).map { |e| e[:message] }
-        summary_msg = RubyLLM::Message.new(role: :system, content: summary_text)
-        @result_messages = [summary_msg] + remaining
-      end
-    end
-  end
-end

data/lib/phronomy/context/trigger_context.rb

@@ -1,39 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Context
-    # Read-only context passed to the +on_compaction_trigger+ callback.
-    #
-    # The callback inspects the current message list and budget, then returns
-    # a truthy value to trigger compaction or a falsy value to skip it.
-    #
-    # No mutations are allowed through this object; use CompactionContext
-    # (passed to +on_compact+) for actual modifications.
-    #
-    # @example Trigger compaction when messages exceed 80% of the input budget
-    #   on_compaction_trigger do |ctx|
-    #     limit = ctx.budget&.available(used: 0) || Float::INFINITY
-    #     ctx.total_tokens > limit * 0.8
-    #   end
-    class TriggerContext
-      # @return [Array<Hash>] frozen snapshot of message elements
-      #   each element: { seq: Integer, message: Object, tokens: Integer, role: Symbol }
-      attr_reader :message_elements
-
-      # @return [Phronomy::Context::TokenBudget, nil] token budget for this invocation
-      attr_reader :budget
-
-      # @return [Integer] total estimated token count of all message elements
-      attr_reader :total_tokens
-
-      # @param message_elements [Array<Hash>]
-      # @param budget [Phronomy::Context::TokenBudget, nil]
-      # @api private
-      def initialize(message_elements:, budget:)
-        @message_elements = message_elements.dup.freeze
-        @budget = budget
-        @total_tokens = message_elements.sum { |e| e[:tokens] }
-      end
-    end
-  end
-end

data/lib/phronomy/context/trim_context.rb

@@ -1,75 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Context
-    # Context object passed to the +on_trim+ callback registered on an agent class.
-    #
-    # The callback receives a TrimContext and may call #remove to drop specific
-    # messages from the conversation before the LLM is called. Changes affect
-    # only the current invocation; the underlying memory store is not modified.
-    #
-    # Message elements are identified by a +:seq+ integer that is assigned
-    # sequentially (0-based) when messages are loaded from memory each turn.
-    #
-    # @example Remove the oldest two messages when the budget is tight
-    #   on_trim do |ctx|
-    #     if ctx.total_tokens > ctx.budget.available(used: 0) * 0.9
-    #       seqs_to_drop = ctx.message_elements.first(2).map { |e| e[:seq] }
-    #       ctx.remove(seqs_to_drop)
-    #     end
-    #   end
-    class TrimContext
-      # @return [Phronomy::Context::TokenBudget, nil] token budget for this invocation
-      attr_reader :budget
-
-      # @return [Integer] total estimated token count of all current message elements
-      attr_reader :total_tokens
-
-      # @param message_elements [Array<Hash>]
-      #   each element: { seq: Integer, message: Object, tokens: Integer, role: Symbol }
-      # @param budget [Phronomy::Context::TokenBudget, nil]
-      # @api private
-      def initialize(message_elements:, budget:)
-        @message_elements = message_elements.dup
-        @budget = budget
-        recalculate!
-      end
-
-      # Returns a snapshot of the current message elements (defensive copy).
-      # Each element is a Hash with +:seq+, +:message+, +:tokens+, and +:role+.
-      #
-      # @return [Array<Hash>]
-      # @api private
-      def message_elements
-        @message_elements.dup
-      end
-
-      # Remove messages identified by seq numbers.
-      # Calling this multiple times accumulates removals.
-      #
-      # @param seqs [Integer, Array<Integer>] seq number(s) to remove
-      # @return [self]
-      # @api private
-      def remove(seqs)
-        seqs_set = Array(seqs).to_set
-        @message_elements.reject! { |e| seqs_set.include?(e[:seq]) }
-        recalculate!
-        self
-      end
-
-      # Convenience: returns the plain message objects (without element metadata).
-      #
-      # @return [Array]
-      # @api private
-      def messages
-        @message_elements.map { |e| e[:message] }
-      end
-
-      private
-
-      def recalculate!
-        @total_tokens = @message_elements.sum { |e| e[:tokens] }
-      end
-    end
-  end
-end

data/lib/phronomy/deadline.rb

@@ -1,63 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  # A point in time used as an upper bound for an operation.
-  #
-  # Uses the monotonic clock (+Process::CLOCK_MONOTONIC+) internally to avoid
-  # skew from NTP adjustments or DST transitions.
-  #
-  # @example Create a 30-second deadline and check remaining time
-  #   deadline = Phronomy::Deadline.in(30)
-  #   sleep 1
-  #   deadline.remaining_seconds   # => ~29.0
-  #   deadline.expired?            # => false
-  class Deadline
-    # Creates a deadline that expires +seconds+ from now.
-    #
-    # @param seconds [Numeric] seconds from now until expiry
-    # @return [Deadline]
-    # @api private
-    def self.in(seconds)
-      new(Process.clock_gettime(Process::CLOCK_MONOTONIC) + seconds)
-    end
-
-    # @param monotonic_at [Float] absolute monotonic timestamp of expiry
-    # @api private
-    def initialize(monotonic_at)
-      @monotonic_at = monotonic_at
-    end
-
-    # Returns +true+ when the deadline has passed.
-    # @return [Boolean]
-    # @api private
-    def expired?
-      Process.clock_gettime(Process::CLOCK_MONOTONIC) >= @monotonic_at
-    end
-
-    # Seconds remaining until expiry.  Returns 0 when already expired.
-    # @return [Float]
-    # @api private
-    def remaining_seconds
-      remaining = @monotonic_at - Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      [remaining, 0.0].max
-    end
-
-    # Attaches this deadline to a {CancellationToken} by cancelling the token
-    # when the deadline expires.  Uses the Runtime timer queue (a single
-    # background thread shared by all deadlines) instead of spawning one thread
-    # per deadline.
-    #
-    # @param token [CancellationToken]
-    # @param timer_queue [Runtime::TimerQueue, nil] queue to register with;
-    #   defaults to +Phronomy::Runtime.instance.timer_queue+
-    # @return [self]
-    # @api private
-    def attach_to(token, timer_queue: Phronomy::Runtime.instance.timer_queue)
-      seconds = remaining_seconds
-      return self if seconds <= 0
-
-      timer_queue.schedule(seconds: seconds) { token.cancel! }
-      self
-    end
-  end
-end

data/lib/phronomy/embeddings/base.rb

@@ -1,39 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Embeddings
-    # Abstract interface for embedding adapters.
-    #
-    # Concrete implementations must override {#embed} and return a vector
-    # as an +Array<Float>+.
-    class Base
-      # Embed the given text and return a vector representation.
-      #
-      # @param text               [String]                         the text to embed
-      # @param cancellation_token [Phronomy::CancellationToken, nil] optional; raises CancellationError when cancelled
-      # @return [Array<Float>] the embedding vector
-      # @api public
-      def embed(text, cancellation_token = nil)
-        cancellation_token&.raise_if_cancelled!
-        raise NotImplementedError, "#{self.class}#embed is not implemented"
-      end
-
-      # Submits an {#embed} call to {BlockingAdapterPool} and returns a
-      # {BlockingAdapterPool::PendingOperation}.
-      #
-      # @param text               [String]
-      # @param cancellation_token [Phronomy::CancellationToken, nil]
-      # @param timeout            [Numeric, nil] seconds before the operation is abandoned
-      # @return [BlockingAdapterPool::PendingOperation]
-      # @api public
-      def embed_async(text, cancellation_token = nil, timeout: nil)
-        Phronomy::Runtime.instance.blocking_io.submit(
-          timeout: timeout,
-          cancellation_token: cancellation_token
-        ) do
-          embed(text, cancellation_token)
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/embeddings/ruby_llm_embeddings.rb

@@ -1,45 +0,0 @@
-# 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
-
-      # Embed text via RubyLLM.
-      #
-      # @param text               [String]
-      # @param cancellation_token [Phronomy::CancellationToken, nil] optional; raises CancellationError when cancelled
-      # @return [Array<Float>]
-      # @api public
-      def embed(text, cancellation_token = nil)
-        cancellation_token&.raise_if_cancelled!
-        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
-      end
-    end
-  end
-end