phronomy 0.6.0 → 0.7.1

data/lib/phronomy/context/token_budget.rb

@@ -45,6 +45,7 @@ module Phronomy
       # @param max_output_tokens [Integer, nil] explicit output reservation; when nil
       #                                         and model is given, uses max_output_tokens
       # @param overhead          [Integer]      tokens reserved for instructions/tools
+      # @api private
       def initialize(model: nil, context_window: nil, max_output_tokens: nil, overhead: 0)
         @overhead = overhead.to_i
 
@@ -65,6 +66,7 @@ module Phronomy
       # Always >= 0.
       #
       # @return [Integer]
+      # @api private
       def effective_input_limit
         [@context_window - @max_output_tokens - @overhead, 0].max
       end
@@ -73,6 +75,7 @@ module Phronomy
       #
       # @param used [Integer] tokens already committed (e.g. from knowledge injection)
       # @return [Integer] remaining tokens (always >= 0)
+      # @api private
       def available(used: 0)
         [effective_input_limit - used.to_i, 0].max
       end

data/lib/phronomy/context/token_estimator.rb

@@ -9,8 +9,12 @@ module Phronomy
     # any other class.
     #
     # Default approximation: ceil(char_count / 4).
-    # English text averages ~4 chars/token; Japanese text averages ~2 chars/token
-    # so this is a slight underestimate for Japanese.
+    # This heuristic is calibrated for ASCII/Latin text (~4 chars/token).
+    # For CJK languages (Chinese, Japanese, Korean) the actual token count is
+    # approximately 4× higher than the estimate because CJK characters are
+    # typically 1 token each in GPT-4/Claude tokenizers (~1 char/token vs the
+    # 4 char/token assumed here).  Use a tokenizer-backed callable via
+    # +.tokenizer=+ for accurate CJK token counting.
     #
     # Replace the built-in heuristic with any callable via .tokenizer=:
     #
@@ -33,11 +37,13 @@ module Phronomy
         #   In tests, call +TokenEstimator.reset_tokenizer!+ after each test to
         #   prevent cross-test contamination.
         # @param callable [#call, nil]
+        # @api private
         def tokenizer=(callable)
           @tokenizer_mutex.synchronize { @tokenizer = callable }
         end
 
         # @return [#call, nil]
+        # @api private
         def tokenizer
           @tokenizer_mutex.synchronize { @tokenizer }
         end
@@ -52,6 +58,7 @@ module Phronomy
         # @param input [String, Array, #content] a string, a message-like object,
         #   or an Array of message-like objects (each must respond to #content).
         # @return [Integer] estimated token count (>= 0)
+        # @api private
         def estimate(input)
           tok = @tokenizer_mutex.synchronize { @tokenizer }
           case input

data/lib/phronomy/context/trigger_context.rb

@@ -28,6 +28,7 @@ module Phronomy
 
       # @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

data/lib/phronomy/context/trim_context.rb

@@ -28,6 +28,7 @@ module Phronomy
       # @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
@@ -38,6 +39,7 @@ module Phronomy
       # Each element is a Hash with +:seq+, +:message+, +:tokens+, and +:role+.
       #
       # @return [Array<Hash>]
+      # @api private
       def message_elements
         @message_elements.dup
       end
@@ -47,6 +49,7 @@ module Phronomy
       #
       # @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]) }
@@ -57,6 +60,7 @@ module Phronomy
       # Convenience: returns the plain message objects (without element metadata).
       #
       # @return [Array]
+      # @api private
       def messages
         @message_elements.map { |e| e[:message] }
       end

data/lib/phronomy/deadline.rb

@@ -0,0 +1,63 @@
+# 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/diagnostics.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Developer-facing diagnostics for blocking operation detection (Issue #279).
+  #
+  # Provides debug dump utilities that can be called from an IRB / Rails console
+  # or in test helpers to inspect the current state of the Runtime.
+  #
+  # @example Enable diagnostics and print a dump
+  #   Phronomy.configure { |c| c.scheduler_debug = true }
+  #   Phronomy::Diagnostics.dump
+  module Diagnostics
+    # Prints a formatted summary of the current Runtime state to +$stderr+
+    # (or the supplied IO).
+    #
+    # Includes:
+    # - BlockingAdapterPool: active workers, queue depth, abandoned count
+    # - EventLoop: last / max / average lag in milliseconds
+    #
+    # @param out [IO] output destination (default: $stderr)
+    # @return [void]
+    # @api public
+    def self.dump(out: $stderr)
+      snap = Phronomy::Metrics.snapshot
+
+      out.puts "[Phronomy::Diagnostics] Runtime state dump"
+      out.puts "  BlockingAdapterPool:"
+      out.puts "    pool_size       : #{snap[:blocking_pool_size]}"
+      out.puts "    active_count    : #{snap[:blocking_pool_active]}"
+      out.puts "    queue_depth     : #{snap[:blocking_pool_queue_length]}"
+      out.puts "    abandoned_total : #{snap[:blocking_pool_abandoned_total]}"
+      out.puts "  EventLoop:"
+      out.puts "    last_lag_ms     : #{snap[:event_loop_lag_last_ms]}"
+      out.puts "    max_lag_ms      : #{snap[:event_loop_lag_max_ms]}"
+      out.puts "    average_lag_ms  : #{snap[:event_loop_lag_average_ms]}"
+    end
+
+    # Returns the diagnostics state as a plain Hash (useful for JSON export).
+    #
+    # @return [Hash]
+    # @api public
+    def self.snapshot
+      Phronomy::Metrics.snapshot
+    end
+
+    # Raises an error if +invoke+ (blocking) is called from inside an EventLoop
+    # action, preventing accidental scheduler stalls.
+    #
+    # Called by Agent::Base#invoke and Workflow#invoke before executing.
+    #
+    # @raise [Phronomy::SchedulerReentrancyError] when called from EventLoop thread
+    # @return [void]
+    # @api private
+    def self.assert_not_in_event_loop!
+      return unless Phronomy::EventLoop.current?
+
+      raise Phronomy::SchedulerReentrancyError,
+        "Blocking invoke called from inside an EventLoop action. " \
+        "Use invoke_async instead."
+    end
+  end
+end

data/lib/phronomy/embeddings/base.rb

@@ -9,11 +9,31 @@ module Phronomy
     class Base
       # Embed the given text and return a vector representation.
       #
-      # @param text [String] the text to embed
+      # @param text               [String]                         the text to embed
+      # @param cancellation_token [Phronomy::CancellationToken, nil] optional; raises CancellationError when cancelled
       # @return [Array<Float>] the embedding vector
-      def embed(text)
+      # @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

@@ -19,6 +19,7 @@ module Phronomy
       # @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
@@ -27,9 +28,12 @@ module Phronomy
 
       # Embed text via RubyLLM.
       #
-      # @param text [String]
+      # @param text               [String]
+      # @param cancellation_token [Phronomy::CancellationToken, nil] optional; raises CancellationError when cancelled
       # @return [Array<Float>]
-      def embed(text)
+      # @api public
+      def embed(text, cancellation_token = nil)
+        cancellation_token&.raise_if_cancelled!
         opts = {}
         opts[:model] = @model if @model
         opts[:provider] = @provider if @provider

data/lib/phronomy/eval/comparison.rb

@@ -19,6 +19,7 @@ module Phronomy
       ComparisonPair = Data.define(:eval_case, :result_a, :result_b)
 
       # @param scorer [Scorer::Base]
+      # @api public
       def initialize(scorer: Scorer::ExactMatch.new)
         @scorer = scorer
       end
@@ -29,6 +30,7 @@ module Phronomy
       # @param callable_a [#call]
       # @param callable_b [#call]
       # @return [Array<ComparisonPair>]
+      # @api public
       def compare(dataset, callable_a, callable_b)
         runner_a = Runner.new(scorer: @scorer)
         runner_b = Runner.new(scorer: @scorer)

data/lib/phronomy/eval/dataset.rb

@@ -13,6 +13,7 @@ module Phronomy
       include Enumerable
 
       # @param cases [Array<EvalCase>]
+      # @api public
       def initialize(cases = [])
         @cases = cases.freeze
       end
@@ -23,16 +24,19 @@ module Phronomy
       #
       # @param pairs [Array<Hash>]
       # @return [Dataset]
+      # @api public
       def self.from_array(pairs)
         new(pairs.map { |h| EvalCase.new(**h) })
       end
 
       # @yield [EvalCase]
+      # @api public
       def each(&block)
         @cases.each(&block)
       end
 
       # @return [Integer]
+      # @api public
       def size
         @cases.size
       end

data/lib/phronomy/eval/metrics.rb

@@ -11,12 +11,14 @@ module Phronomy
     #   puts metrics.to_h
     class Metrics
       # @param results [Array<EvalResult>]
+      # @api public
       def initialize(results)
         @results = results
       end
 
       # Fraction of results that passed (score == 1.0).
       # @return [Float] in [0.0, 1.0]
+      # @api public
       def pass_rate
         return 0.0 if @results.empty?
         @results.count(&:pass?).to_f / @results.size
@@ -24,6 +26,7 @@ module Phronomy
 
       # Arithmetic mean of all scores.
       # @return [Float]
+      # @api public
       def average_score
         return 0.0 if @results.empty?
         @results.sum(&:score) / @results.size
@@ -32,12 +35,14 @@ module Phronomy
       # Sum of all TokenUsage objects present in the results.
       # Results without usage are skipped.
       # @return [Phronomy::TokenUsage]
+      # @api public
       def total_usage
         @results.map(&:usage).compact.reduce(TokenUsage.zero, :+)
       end
 
       # Arithmetic mean of latency_ms across all results.
       # @return [Float]
+      # @api public
       def average_latency_ms
         return 0.0 if @results.empty?
         @results.sum(&:latency_ms).to_f / @results.size
@@ -45,6 +50,7 @@ module Phronomy
 
       # Returns a plain Hash summary suitable for logging or serialisation.
       # @return [Hash]
+      # @api public
       def to_h
         {
           total: @results.size,

data/lib/phronomy/eval/runner.rb

@@ -18,6 +18,7 @@ module Phronomy
     #   results = runner.run(dataset, ->(input) { agent.invoke(input) })
     class Runner
       # @param scorer [Scorer::Base] scorer used to evaluate each result
+      # @api public
       def initialize(scorer: Scorer::ExactMatch.new)
         @scorer = scorer
       end
@@ -26,29 +27,30 @@ module Phronomy
       # @param callable    [#call]    accepts a single String argument
       # @param concurrency [Integer]  number of parallel threads (default: 1, sequential)
       # @return [Array<EvalResult>]
+      # @api public
       def run(dataset, callable, concurrency: 1)
         cases = dataset.to_a
         return cases.map { |eval_case| run_one(eval_case, callable) } if concurrency <= 1
 
-        # Run cases in slices of +concurrency+ threads. Each slice is joined
-        # before the next starts, bounding peak thread count to +concurrency+.
-        # Writing to pre-allocated slots (one per thread) is safe because each
-        # thread writes to a unique index and all threads in a slice are joined
+        # Run cases in slices of +concurrency+ tasks. Each slice is joined
+        # before the next starts, bounding peak task count to +concurrency+.
+        # Writing to pre-allocated slots (one per task) is safe because each
+        # task writes to a unique index and all tasks in a slice are joined
         # before the next slice begins.
-        # Exceptions in worker threads are collected and re-raised after all
-        # threads in the slice are joined, preventing orphaned threads.
+        # Exceptions in worker tasks are collected and re-raised after all
+        # tasks in the slice are joined, preventing orphaned tasks.
         results = Array.new(cases.length)
         cases.each_with_index.each_slice(concurrency) do |batch|
           errors = []
           errors_mu = Mutex.new
-          threads = batch.map do |eval_case, i|
-            Thread.new do
+          tasks = batch.map do |eval_case, i|
+            Phronomy::Runtime.instance.spawn(name: "eval-case-#{i}") do
               results[i] = run_one(eval_case, callable)
             rescue => e
               errors_mu.synchronize { errors << e }
             end
           end
-          threads.each(&:join)
+          tasks.each(&:join)
           raise errors.first if errors.any?
         end
         results

data/lib/phronomy/eval/scorer/base.rb

@@ -12,6 +12,7 @@ module Phronomy
         # @param expected [String] the ground-truth value from the EvalCase
         # @param input    [String, nil] the original input (used by LLM scorers)
         # @return [Float] a value in [0.0, 1.0]
+        # @api public
         def score(actual:, expected:, input: nil)
           raise NotImplementedError, "#{self.class}#score is not implemented"
         end

data/lib/phronomy/eval/scorer/exact_match.rb

@@ -12,11 +12,13 @@ module Phronomy
       #   ExactMatch.new.score(actual: "paris", expected: "Paris")  # => 0.0
       class ExactMatch < Base
         # @param case_sensitive [Boolean] default true
+        # @api public
         def initialize(case_sensitive: true)
           @case_sensitive = case_sensitive
         end
 
         # @return [Float] 1.0 on match, 0.0 otherwise
+        # @api public
         def score(actual:, expected:, input: nil)
           a = actual.to_s.strip
           e = expected.to_s.strip

data/lib/phronomy/eval/scorer/includes_scorer.rb

@@ -13,11 +13,13 @@ module Phronomy
       #   IncludesScorer.new.score(actual: "The answer is 42.", expected: "42")  # => 1.0
       class IncludesScorer < Base
         # @param case_sensitive [Boolean] default false
+        # @api public
         def initialize(case_sensitive: false)
           @case_sensitive = case_sensitive
         end
 
         # @return [Float] 1.0 if actual contains expected, 0.0 otherwise
+        # @api public
         def score(actual:, expected:, input: nil)
           a = actual.to_s
           e = expected.to_s

data/lib/phronomy/eval/scorer/llm_judge.rb

@@ -36,6 +36,7 @@ module Phronomy
         # @param prompt_template [String]  format string with %<input>s, %<expected>s, %<actual>s
         # @param raise_on_error  [Boolean] when true, re-raises scoring exceptions instead of
         #   returning 0.0. Use this in batch eval pipelines where silent failures are unacceptable.
+        # @api public
         def initialize(model:, prompt_template: DEFAULT_PROMPT, raise_on_error: false)
           @model = model
           @prompt_template = prompt_template
@@ -43,6 +44,7 @@ module Phronomy
         end
 
         # @return [Float] score in [0.0, 1.0]; 0.0 on error when raise_on_error is false
+        # @api public
         def score(actual:, expected:, input: nil)
           prompt = format(@prompt_template, input: input.to_s, expected: expected.to_s, actual: actual.to_s)
           response = RubyLLM.chat(model: @model).ask(prompt)