phronomy 0.6.0 → 0.7.0

data/lib/phronomy/cancellation_token.rb

@@ -0,0 +1,92 @@
+# 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
+    end
+
+    # @return [Time, nil] the wall-clock deadline passed to {#initialize}, or +nil+.
+    attr_reader :deadline
+
+    # Mark the token as cancelled. Thread-safe; may be called from any thread.
+    # @return [self]
+    # @api public
+    def cancel!
+      @mutex.synchronize { @cancelled = true }
+      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/configuration.rb

@@ -33,16 +33,40 @@ module Phronomy
     # @see Phronomy::EventLoop
     attr_accessor :event_loop
 
-    # When true (default), user input and LLM output are recorded in trace spans.
+    # When true, user input and LLM output are recorded in trace spans.
+    # Defaults to false; set to true only in environments where PII capture is acceptable.
     # Set to false in privacy-sensitive environments to prevent PII from reaching
     # the tracing backend (OTel, Langfuse, etc.).
     attr_accessor :trace_pii
 
+    # Optional logger for framework diagnostic messages (e.g. unreachable-state warnings).
+    # Must respond to +#warn(message)+.  When nil (default), messages are written to +$stderr+
+    # via +Kernel#warn+.
+    # @example
+    #   Phronomy.configure { |c| c.logger = Rails.logger }
+    attr_accessor :logger
+
+    # Grace period (in seconds) before the EventLoop background thread is force-killed
+    # after a cooperative stop request.  Applies both to the overall thread join
+    # and to the drain-and-cancel phase when +stop(drain: true)+ is used.
+    # Default: 5 seconds.
+    # @see Phronomy::EventLoop#stop
+    attr_accessor :event_loop_stop_grace_seconds
+
+    # Global state store for workflow persistence.
+    # When set, WorkflowRunner routes all state reads and writes through this store.
+    # Must be an instance of a class that inherits from Phronomy::StateStore::Base.
+    # Defaults to +nil+ (no persistence — state lives only for the duration of invoke).
+    # @example
+    #   Phronomy.configure { |c| c.state_store = Phronomy::StateStore::InMemory.new }
+    attr_accessor :state_store
+
     def initialize
       @recursion_limit = 25
       @tracer = Phronomy::Tracing::NullTracer.new
-      @trace_pii = true
+      @trace_pii = false
       @event_loop = false
+      @event_loop_stop_grace_seconds = 5
     end
   end
 end

data/lib/phronomy/context/assembler.rb

@@ -35,12 +35,14 @@ module Phronomy
       # @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
@@ -53,6 +55,7 @@ module Phronomy
       #
       # @param text [String]
       # @return [self]
+      # @api private
       def add_instruction(text)
         @instruction = text.to_s
         self
@@ -67,6 +70,7 @@ module Phronomy
       # @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
@@ -76,6 +80,7 @@ module Phronomy
       #
       # @param messages [Array] message-like objects with #role and #content
       # @return [self]
+      # @api private
       def add_messages(messages)
         @messages = Array(messages)
         self
@@ -86,6 +91,7 @@ module Phronomy
       # @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

data/lib/phronomy/context/compaction_context.rb

@@ -45,6 +45,7 @@ module Phronomy
       # @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
@@ -67,6 +68,7 @@ module Phronomy
       # @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]

data/lib/phronomy/context/context_version_cache.rb

@@ -25,6 +25,7 @@ module Phronomy
       #
       # @param fingerprint [String] SHA-256 hex digest to compare
       # @return [Boolean]
+      # @api private
       def valid?(fingerprint)
         !@fingerprint.nil? && !@system_text.nil? && @fingerprint == fingerprint
       end
@@ -33,6 +34,7 @@ module Phronomy
       #
       # @param fingerprint  [String] new SHA-256 hex digest
       # @param system_text  [String] fully assembled system prompt text
+      # @api private
       def update(fingerprint:, system_text:)
         @fingerprint = fingerprint
         @system_text = system_text.to_s

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/embeddings/base.rb

@@ -9,9 +9,12 @@ 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
     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,6 +27,7 @@ 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

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)