phronomy 0.7.1 → 0.9.0

data/lib/phronomy/cancellation_scope.rb

@@ -1,123 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  # Represents a bounded execution scope that owns a {CancellationToken} and
-  # optionally a {Deadline}.
-  #
-  # +CancellationScope+ replaces ad-hoc +Timeout.timeout+ calls in agent and
-  # tool code.  All work performed within a scope should observe the scope's
-  # token; when the scope is cancelled (explicitly or by deadline expiry) the
-  # token is cancelled and all child tasks that check it will stop.
-  #
-  # @example Time-bounded invocation
-  #   scope = Phronomy::CancellationScope.new.deadline_in(30)
-  #   result = scope.pop_queue(completion_queue) do
-  #     raise Phronomy::TimeoutError, "timed out"
-  #   end
-  #
-  # @example Explicit cancellation
-  #   scope = Phronomy::CancellationScope.new
-  #   Phronomy::Runtime.instance.spawn(name: "worker") do
-  #     scope.token.raise_if_cancelled!
-  #     # ... do work ...
-  #   end
-  #   scope.cancel! if some_condition
-  class CancellationScope
-    # @return [CancellationToken] the token owned by this scope
-    attr_reader :token
-
-    # @return [Deadline, nil] the deadline attached to this scope, if any
-    attr_reader :deadline
-
-    # @param parent_token [CancellationToken, nil] when provided, cancellation of
-    #   the parent token is propagated to this scope's token via a callback
-    #   (for explicit cancel) and/or the Runtime timer queue (for monotonic
-    #   deadline expiry).  No polling thread is spawned.
-    # @api private
-    def initialize(parent_token: nil)
-      @token = Phronomy::CancellationToken.new
-      @deadline = nil
-
-      if parent_token
-        # Propagate explicit cancel() from parent to child via callback.
-        parent_token.on_cancel { @token.cancel! }
-
-        # Propagate monotonic-deadline expiry from parent to child via the
-        # timer queue (avoids a polling thread).
-        remaining = parent_token.remaining_monotonic_seconds
-        if !remaining.nil?
-          if remaining <= 0
-            @token.cancel!
-          else
-            Phronomy::Runtime.instance.timer_queue.schedule(seconds: remaining) do
-              @token.cancel!
-            end
-          end
-        end
-      end
-    end
-
-    # Attaches a deadline that will cancel this scope after +seconds+.
-    #
-    # @param seconds [Numeric] timeout duration
-    # @return [self]
-    # @api private
-    def deadline_in(seconds)
-      @deadline = Phronomy::Deadline.in(seconds)
-      @deadline.attach_to(@token)
-      self
-    end
-
-    # Cancels this scope immediately.
-    # @return [void]
-    # @api private
-    def cancel!
-      @token.cancel!
-    end
-
-    # Returns +true+ if this scope has been cancelled.
-    # @return [Boolean]
-    # @api private
-    def cancelled?
-      @token.cancelled?
-    end
-
-    # Returns the remaining time in seconds before the deadline expires,
-    # or +nil+ when no deadline is set.
-    # @return [Float, nil]
-    # @api private
-    def remaining_seconds
-      @deadline&.remaining_seconds
-    end
-
-    # Pops from +queue+ with a timeout derived from the attached deadline (or
-    # +fallback_timeout+ seconds when no deadline is set).  If the pop times out,
-    # the scope is cancelled and the block is called (or a {TimeoutError} raised).
-    #
-    # @param queue [Phronomy::AsyncQueue] the queue to pop from
-    # @param fallback_timeout [Numeric, nil] used when no deadline is attached
-    # @yield called when the operation times out
-    # @raise [Phronomy::TimeoutError] when no block is given and a timeout occurs
-    # @return [Object] the popped value
-    # @api private
-    def pop_queue(queue, fallback_timeout: nil)
-      timeout = @deadline&.remaining_seconds || fallback_timeout
-      result = if timeout
-        queue.pop(timeout: timeout)
-      else
-        queue.pop
-      end
-
-      if result.nil?
-        cancel!
-        if block_given?
-          yield
-        else
-          raise Phronomy::TimeoutError, "CancellationScope timed out"
-        end
-      end
-
-      result
-    end
-  end
-end

data/lib/phronomy/cancellation_token.rb

@@ -1,133 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  # Provides cooperative cancellation for agent invocations.
-  #
-  # Pass a token to an agent via +config: { cancellation_token: token }+.
-  # The agent checks the token before each LLM call and raises
-  # {Phronomy::CancellationError} when the token is cancelled or the
-  # optional deadline has passed.
-  #
-  # A token may be shared across multiple agent invocations and across threads;
-  # all access to internal state is protected by a Mutex.
-  #
-  # @example Explicit cancel from another thread
-  #   token = Phronomy::CancellationToken.new
-  #   Thread.new { sleep 5; token.cancel! }
-  #   result = agent.invoke("...", config: { cancellation_token: token })
-  #
-  # @example Hard deadline via monotonic clock (recommended)
-  #   token = Phronomy::CancellationToken.timeout_after(30)
-  #   result = agent.invoke("...", config: { cancellation_token: token })
-  #
-  # @example Hard deadline via wall-clock (legacy)
-  #   token = Phronomy::CancellationToken.new(deadline: Time.now + 30)
-  #   result = agent.invoke("...", config: { cancellation_token: token })
-  #
-  # @example Propagate to parallel workers
-  #   token = Phronomy::CancellationToken.new
-  #   orchestrator.dispatch_parallel(task1, task2, cancellation_token: token)
-  class CancellationToken
-    # Returns a new token that will expire after +seconds+ seconds, measured
-    # with the monotonic clock (+Process::CLOCK_MONOTONIC+). Unlike constructing
-    # a token with +deadline: Time.now + seconds+, this factory is immune to NTP
-    # adjustments and DST transitions.
-    #
-    # @param seconds [Numeric] duration in seconds until the token expires.
-    # @return [CancellationToken]
-    # @api public
-    def self.timeout_after(seconds)
-      monotonic_deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + seconds
-      new(monotonic_deadline: monotonic_deadline)
-    end
-
-    # @param deadline [Time, nil] optional wall-clock deadline; the token reports
-    #   +cancelled?+ as +true+ once +Time.now >= deadline+.  Prefer
-    #   {.timeout_after} for duration-based cancellation.
-    # @param monotonic_deadline [Float, nil] internal monotonic timestamp set by
-    #   {.timeout_after}; prefer that factory method over passing this directly.
-    # @api public
-    def initialize(deadline: nil, monotonic_deadline: nil)
-      @cancelled = false
-      @deadline = deadline
-      @monotonic_deadline = monotonic_deadline
-      @mutex = Mutex.new
-      @cancel_callbacks = []
-    end
-
-    # @return [Time, nil] the wall-clock deadline passed to {#initialize}, or +nil+.
-    attr_reader :deadline
-
-    # Returns the remaining seconds until the monotonic deadline fires, or +nil+
-    # when no monotonic deadline is set.  Returns 0.0 if already past.
-    # @return [Float, nil]
-    # @api public
-    def remaining_monotonic_seconds
-      return nil if @monotonic_deadline.nil?
-      remaining = @monotonic_deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      [remaining, 0.0].max
-    end
-
-    # Registers a one-shot callback invoked when this token is explicitly
-    # cancelled via {#cancel!}.  If the token is already cancelled, the block
-    # is called immediately (still within the caller's thread).
-    #
-    # Callbacks are NOT fired for deadline-based cancellation (i.e. when
-    # {#cancelled?} returns +true+ due to +@monotonic_deadline+ expiry).  Use
-    # {Runtime#timer_queue} to schedule deadline callbacks.
-    #
-    # @yield called with no arguments when (or if) the token is cancelled
-    # @return [self]
-    # @api public
-    def on_cancel(&block)
-      already_cancelled = @mutex.synchronize do
-        if @cancelled
-          true
-        else
-          @cancel_callbacks << block
-          false
-        end
-      end
-      block.call if already_cancelled
-      self
-    end
-
-    # Mark the token as cancelled and fire any registered {#on_cancel} callbacks.
-    # Thread-safe; idempotent — calling multiple times has no additional effect.
-    # @return [self]
-    # @api public
-    def cancel!
-      callbacks = @mutex.synchronize do
-        return self if @cancelled
-        @cancelled = true
-        @cancel_callbacks.dup
-      end
-      callbacks.each(&:call)
-      self
-    end
-
-    # Returns +true+ when the token has been explicitly cancelled via {#cancel!},
-    # when the wall-clock deadline has passed, or when the monotonic deadline
-    # (set by {.timeout_after}) has elapsed. Thread-safe.
-    # @return [Boolean]
-    # @api public
-    def cancelled?
-      return true if @mutex.synchronize { @cancelled }
-      return true if !@deadline.nil? && Time.now >= @deadline
-      !@monotonic_deadline.nil? &&
-        Process.clock_gettime(Process::CLOCK_MONOTONIC) >= @monotonic_deadline
-    end
-
-    # Raises {Phronomy::CancellationError} if the token is cancelled.
-    # A convenience method for cooperative cancellation checks inside tools,
-    # RAG loaders, and hooks, replacing the +if cancelled? then raise+ pattern.
-    #
-    # @param message [String] optional error message
-    # @return [nil] when the token is not cancelled
-    # @raise [Phronomy::CancellationError] when the token is cancelled
-    # @api public
-    def raise_if_cancelled!(message = "invocation cancelled")
-      raise Phronomy::CancellationError, message if cancelled?
-    end
-  end
-end

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/assembler.rb

@@ -1,143 +0,0 @@
-# frozen_string_literal: true
-
-require "cgi"
-
-module Phronomy
-  module Context
-    # Assembler collects all four context regions and produces the final
-    # {system:, messages:} hash consumed by Agent::Base.
-    #
-    # Regions:
-    #   1. Instruction  — system prompt text set via #add_instruction
-    #   2. Capability   — tool definitions (handled by RubyLLM, not here)
-    #   3. Knowledge    — external facts injected via #add_knowledge (generates XML tags)
-    #   4. Conversation — historical messages added via #add_messages
-    #
-    # Token budgeting:
-    #   When a budget is given, conversation messages are trimmed from oldest to
-    #   newest until they fit. Knowledge chunks are always included in full (they
-    #   are assumed to be pre-screened by the caller). When no budget is given all
-    #   messages are passed through unchanged.
-    #
-    # @example
-    #   assembler = Phronomy::Context::Assembler.new(budget: budget)
-    #   assembler.add_instruction("You are a helpful assistant.")
-    #   assembler.add_knowledge("The user lives in Tokyo.", type: :entity, trusted: false)
-    #   assembler.add_messages(manager.load(thread_id: "t1", query: user_input))
-    #   context = assembler.build
-    #   # => { system: "You are ...\n<context ...>...</context>", messages: [...] }
-    class Assembler
-      # Builds a single XML context tag string.
-      # Exposed as a class method so callers (e.g. Agent::Base) can build
-      # static knowledge XML tags independently of an Assembler instance.
-      #
-      # @param text    [String]
-      # @param type    [Symbol, String]
-      # @param trusted [Boolean]
-      # @return [String]
-      # @api private
-      def self.xml_tag(text, type:, trusted: false)
-        "<context type=\"#{CGI.escapeHTML(type.to_s)}\" trusted=\"#{trusted}\">\n#{CGI.escapeHTML(text.to_s)}\n</context>"
-      end
-
-      # @param budget [Phronomy::Context::TokenBudget, nil]
-      #   when nil no token trimming is performed
-      # @api private
-      def initialize(budget: nil)
-        @budget = budget
-        @instruction = nil
-        @knowledge_chunks = []
-        @messages = []
-      end
-
-      # Set the system instruction text (Region 1).
-      # Calling this multiple times replaces the previous value.
-      #
-      # @param text [String]
-      # @return [self]
-      # @api private
-      def add_instruction(text)
-        @instruction = text.to_s
-        self
-      end
-
-      # Append a knowledge chunk (Region 3).
-      # The chunk is wrapped in an XML context tag automatically.
-      #
-      # @param text    [String]
-      # @param type    [Symbol, String]  semantic label for the context tag (e.g. :entity, :rag, :static)
-      # @param trusted [Boolean]         false (default) indicates externally sourced data
-      # @param source  [String, nil]     optional source label (e.g. filename); included in the
-      #   XML tag so the LLM can produce grounded citations. Omitted when nil.
-      # @return [self]
-      # @api private
-      def add_knowledge(text, type:, trusted: false, source: nil)
-        @knowledge_chunks << {text: text.to_s, type: type.to_s, trusted: trusted, source: source}
-        self
-      end
-
-      # Set conversation messages (Region 4). Replaces any previously set messages.
-      #
-      # @param messages [Array] message-like objects with #role and #content
-      # @return [self]
-      # @api private
-      def add_messages(messages)
-        @messages = Array(messages)
-        self
-      end
-
-      # Assemble the context.
-      #
-      # @return [Hash{Symbol => Object}]
-      #   :system   [String, nil]  combined system prompt (instruction + knowledge XML tags)
-      #   :messages [Array]        conversation messages, trimmed to budget if set
-      # @api private
-      def build
-        knowledge_text = @knowledge_chunks.map { |c| xml_context_tag(c) }.join("\n\n")
-        system_parts = [@instruction, knowledge_text.empty? ? nil : knowledge_text].compact
-        system_text = system_parts.join("\n\n")
-
-        messages = if @budget
-          trim_messages_to_budget(@messages, system_text)
-        else
-          @messages
-        end
-
-        {
-          system: system_text.empty? ? nil : system_text,
-          messages: messages
-        }
-      end
-
-      private
-
-      def xml_context_tag(chunk)
-        src_attr = chunk[:source] ? " source=\"#{CGI.escapeHTML(chunk[:source].to_s)}\"" : ""
-        "<context type=\"#{CGI.escapeHTML(chunk[:type].to_s)}\"#{src_attr} trusted=\"#{chunk[:trusted]}\">\n#{CGI.escapeHTML(chunk[:text].to_s)}\n</context>"
-      end
-
-      def trim_messages_to_budget(messages, system_text)
-        used = TokenEstimator.estimate(system_text)
-        remaining = @budget.available(used: used)
-        return messages if remaining <= 0 && messages.empty?
-
-        accumulated = 0
-        result = []
-        messages.reverse_each do |msg|
-          tokens = TokenEstimator.estimate(msg.content.to_s)
-          break if accumulated + tokens > remaining
-
-          accumulated += tokens
-          result.push(msg)
-        end
-
-        if result.empty? && messages.any?
-          warn "[Phronomy::Assembler] All #{messages.length} conversation message(s) dropped: " \
-               "token budget exhausted by system context (budget=#{@budget.context_window}, used_by_system=#{used})"
-        end
-
-        result.reverse
-      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