phronomy 0.5.4 → 0.7.0

data/lib/phronomy/agent/shared_state.rb

@@ -57,6 +57,7 @@ module Phronomy
 
         # Returns a shallow copy of all findings in insertion order.
         # @return [Array<Hash>]
+        # @api public
         def read_all
           @findings.dup
         end
@@ -66,6 +67,7 @@ module Phronomy
         # @param content [String]  the finding text
         # @param cycle   [Integer] the current cycle number
         # @return [nil]
+        # @api public
         def write(agent:, content:, cycle:)
           @findings << {agent: agent, content: content, cycle: cycle}
           nil
@@ -73,6 +75,7 @@ module Phronomy
 
         # Returns the number of findings recorded so far.
         # @return [Integer]
+        # @api public
         def size
           @findings.size
         end
@@ -85,6 +88,7 @@ module Phronomy
         # @param klass [Class] an Agent::Base subclass
         # @param instruction [String, nil] optional per-agent coordination instruction
         #   appended to the team coordination text in this agent's prompt
+        # @api public
         def member(klass, instruction: nil)
           @members ||= []
           @members << {klass: klass, instruction: instruction}
@@ -94,6 +98,7 @@ module Phronomy
         # per-agent instruction. Prefer {.member} for new code.
         #
         # @param classes [Array<Class>] Agent::Base subclasses
+        # @api public
         def researchers(*classes)
           classes.flatten.each { |klass| member(klass) }
         end
@@ -104,6 +109,7 @@ module Phronomy
         # workflow. Override this when you need a different protocol or tone.
         #
         # @param text [String, nil] the coordination instructions
+        # @api public
         def coordination(text = nil)
           text ? @coordination = text : @coordination
         end
@@ -112,6 +118,7 @@ module Phronomy
         # At least one of +max_cycles+ or +timeout+ must be configured.
         #
         # @param value [Integer, nil]
+        # @api public
         def max_cycles(value = nil)
           value ? @max_cycles = Integer(value) : @max_cycles
         end
@@ -120,6 +127,7 @@ module Phronomy
         # At least one of +max_cycles+ or +timeout+ must be configured.
         #
         # @param value [Numeric, nil]
+        # @api public
         def timeout(value = nil)
           value ? @timeout = value.to_f : @timeout
         end
@@ -128,6 +136,7 @@ module Phronomy
         # cycle; when it returns +true+ the loop terminates early.
         #
         # @yield [KnowledgeStore] receives the store; return +true+ to stop
+        # @api public
         def terminate_when(&block)
           block ? @terminate_when = block : @terminate_when
         end
@@ -136,6 +145,7 @@ module Phronomy
         # When omitted, +store.read_all+ is used as-is.
         #
         # @yield [KnowledgeStore] receives the final store; return value becomes +:output+
+        # @api public
         def aggregate(&block)
           block ? @aggregator = block : @aggregator
         end
@@ -162,6 +172,7 @@ module Phronomy
       # @param config [Hash]   reserved for future use
       # @return [Hash] +:output+, +:cycles+, +:terminated_by+
       # @raise [ArgumentError] when neither +max_cycles+ nor +timeout+ is configured
+      # @api public
       def invoke(input, config: {})
         validate_termination!
 

data/lib/phronomy/agent/suspend_signal.rb

@@ -8,6 +8,7 @@ module Phronomy
     # suspended result hash containing a Checkpoint.
     #
     # This class is intentionally NOT part of the public API.  Callers should
+    # @api private
     # inspect the +:suspended+ key in the result hash returned by #invoke.
     #
     # @api private
@@ -24,6 +25,7 @@ module Phronomy
       # @param tool_name    [String]
       # @param args         [Hash]
       # @param tool_call_id [String]
+      # @api private
       def initialize(tool_name:, args:, tool_call_id:)
         super("Agent suspended waiting for approval of tool: #{tool_name}")
         @tool_name = tool_name

data/lib/phronomy/agent/team_coordinator.rb

@@ -7,9 +7,13 @@ module Phronomy
     # @see https://claude.com/blog/multi-agent-coordination-patterns
     #
     # A coordinator LLM agent decomposes work into tasks and enqueues them
-    # dynamically via built-in tools. A fixed pool of worker agents claims tasks
-    # from the shared queue, carrying forward their conversation history across
-    # assignments to accumulate domain context over time.
+    # dynamically via built-in tools. A fixed set of worker agents processes tasks
+    # sequentially — one task per worker per turn — carrying forward their
+    # conversation history across assignments to accumulate domain context over time.
+    #
+    # Workers are selected in sequence (the worker with the fewest accumulated
+    # messages is chosen by default). Task dispatch is synchronous; there is no
+    # concurrent or parallel execution.
     #
     # The coordinator is an {Agent::Base} subclass that has two built-in tools:
     # - +enqueue_task+ — adds a task description to the queue
@@ -56,6 +60,7 @@ module Phronomy
         # Falls back to +Phronomy.configuration.default_model+ when not set.
         #
         # @param value [String, nil]
+        # @api public
         def coordinator_model(value = nil)
           value ? @coordinator_model = value : @coordinator_model
         end
@@ -65,6 +70,7 @@ module Phronomy
         # and then call +finalize+ when all tasks are enqueued.
         #
         # @param value [String, nil]
+        # @api public
         def coordinator_instructions(value = nil)
           value ? @coordinator_instructions = value : @coordinator_instructions
         end
@@ -75,16 +81,18 @@ module Phronomy
         # Pass the same value as +LLMConfig::PROVIDER+ in your examples.
         #
         # @param value [Symbol, nil]
+        # @api public
         def coordinator_provider(value = nil)
           value ? @coordinator_provider = value : @coordinator_provider
         end
 
-        # Configures the worker pool.
+        # Configures the set of workers.
         #
-        # @param size     [Integer] number of persistent worker instances
+        # @param size     [Integer] number of persistent worker instances (tasks are assigned sequentially)
         # @param agent    [Class]   Agent::Base subclass used for all workers
         # @param on_error [Symbol]  +:raise+ (default) propagates worker exceptions;
         #                           +:skip+ records the failure and continues with remaining tasks
+        # @api public
         def pool(size:, agent:, on_error: :raise)
           @pool_size = Integer(size)
           @worker_agent = agent
@@ -98,6 +106,7 @@ module Phronomy
         #
         # @yield [Array<WorkerState>] available workers
         # @yieldreturn [WorkerState] the chosen worker
+        # @api public
         def schedule(&block)
           @scheduler = block
         end
@@ -108,6 +117,7 @@ module Phronomy
         # When omitted, the raw assignments array is returned.
         #
         # @yield [Array<Hash>] all completed (and skipped) task assignments
+        # @api public
         def aggregate(&block)
           @aggregator = block
         end
@@ -137,6 +147,7 @@ module Phronomy
       # @param config     [Hash]         reserved for future use
       # @return [Object] the return value of the aggregate block, or the raw assignments Array
       # @raise [ArgumentError] when +pool :agent+ has not been configured
+      # @api public
       def invoke(team_input, config: {})
         raise ArgumentError, "pool :agent must be configured before invoking" unless self.class._worker_agent
 
@@ -161,6 +172,7 @@ module Phronomy
       # @yield [Hash] one event per completed/failed task
       # @return [Object] same as +invoke+
       # @raise [ArgumentError] when +pool :agent+ has not been configured
+      # @api public
       def stream(team_input, config: {}, &block)
         return invoke(team_input, config: config) unless block
 

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

@@ -28,15 +28,45 @@ module Phronomy
     # Recursion limit for graph execution (default: 25)
     attr_accessor :recursion_limit
 
-    # When true (default), user input and LLM output are recorded in trace spans.
+    # When true, workflow execution is driven by EventLoop instead of a
+    # synchronous loop in the calling thread. Defaults to false (sync mode).
+    # @see Phronomy::EventLoop
+    attr_accessor :event_loop
+
+    # 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/context.rb

@@ -7,7 +7,6 @@ module Phronomy
   # Sub-modules are auto-loaded by Zeitwerk:
   #   Phronomy::Context::TokenEstimator
   #   Phronomy::Context::TokenBudget
-  #   Phronomy::Context::Builder
   module Context
   end
 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