phronomy 0.5.4 → 0.7.0

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)

data/lib/phronomy/event.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Immutable event struct used for inter-FSM communication via EventLoop.
+  #
+  # @param type      [Symbol]  event identifier (:start, :state_completed,
+  #                            :finished, :halted, :error, or any user-defined name)
+  # @param target_id [String]  FSMSession identifier — matches WorkflowContext#thread_id
+  # @param payload   [Object]  optional data attached to the event:
+  #                            - final/halted context for :finished/:halted
+  #                            - Exception for :error
+  #                            - nil for :start / :state_completed
+  Event = Data.define(:type, :target_id, :payload)
+end

data/lib/phronomy/event_loop.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Singleton event loop that manages all FSMSession instances.
+  #
+  # A single background thread reads from a global Thread::Queue and dispatches
+  # events to their target FSMSession. IO work (LLM calls, tool calls) runs in
+  # separate IO threads that post events back to the loop via EventLoop#post.
+  #
+  # Activated with: +Phronomy.configure { |c| c.event_loop = true }+
+  #
+  # == Fork safety
+  #
+  # +EventLoop.instance+ is lazily initialized. The background thread is not
+  # created until the first call, so Puma worker forking does not duplicate the
+  # thread. No +after_fork+ hook is required.
+  #
+  # == Deadlock warning
+  #
+  # Do NOT call +Workflow#invoke+ (in EventLoop mode) from within a workflow
+  # entry action. The entry action runs on the EventLoop thread; a nested
+  # +invoke+ would block waiting for the same thread to process events →
+  # deadlock. Use the async IO pattern instead (spawn a Thread, post events
+  # back to the EventLoop).
+  class EventLoop
+    # Returns the singleton instance, creating and starting it on first call.
+    def self.instance
+      @instance ||= new.tap(&:start)
+    end
+
+    # Stops and destroys the singleton. Primarily used in tests.
+    # @api private
+    def self.reset!
+      @instance&.stop
+      @instance = nil
+    end
+
+    def initialize
+      @queue = Thread::Queue.new  # global event queue (thread-safe; no Mutex needed)
+      @fsms = {}                  # { id => FSMSession }     — EventLoop thread only
+      @waiting = {}               # { id => completion_queue } — EventLoop thread only
+      # Mutex-backed FSM count for drain-mode shutdown.
+      @fsm_count_mutex = Mutex.new
+      @fsm_count_cond = ConditionVariable.new
+      @fsm_count = 0
+      # Token cancelled when shutdown is requested; new child sessions receive it.
+      @shutdown_token = Phronomy::CancellationToken.new
+    end
+
+    # Registers an FSMSession for execution and returns a completion queue.
+    #
+    # The session and its completion queue are handed off to the EventLoop thread
+    # via the queue payload, so +@fsms+ and +@waiting+ are exclusively written
+    # and read by the EventLoop thread. No Mutex is required.
+    #
+    # The caller blocks on +completion_queue.pop+ to receive the final context
+    # (WorkflowContext) once the workflow finishes or halts. If an error occurred,
+    # the popped value will be an Exception — callers are responsible for re-raising it.
+    #
+    # @param fsm_session [Phronomy::FSMSession]
+    # @return [Thread::Queue] resolves to final/halted context, or an Exception
+    # @api private
+    def register(fsm_session)
+      if Thread.current[:phronomy_event_loop_thread]
+        raise Phronomy::Error,
+          "Cannot call Workflow#invoke (EventLoop mode) from within an EventLoop " \
+          "entry action. Use the async IO pattern: spawn a Thread, post events " \
+          "back via Phronomy::EventLoop.instance.post(...) instead."
+      end
+
+      completion_queue = Thread::Queue.new
+      # Pass both session and completion_queue in the event payload so that the
+      # EventLoop thread is the sole writer of @fsms and @waiting.
+      @queue.push(Event.new(type: :start, target_id: fsm_session.id,
+        payload: {session: fsm_session, completion: completion_queue}))
+      completion_queue
+    end
+
+    # Enqueues an {AgentFSM} as a fire-and-forget child session.
+    #
+    # Unlike {#register}, this method:
+    # - Is safe to call from the EventLoop thread (entry actions).
+    # - Does NOT block — no completion queue is created.
+    # - Delegates `:finished`/`:error` cleanup to the EventLoop via posted events.
+    #
+    # @param agent_fsm [Phronomy::Agent::FSM]
+    # @return [nil]
+    # @api private
+    def enqueue_child(agent_fsm)
+      @queue.push(Event.new(type: :start, target_id: agent_fsm.id,
+        payload: {session: agent_fsm, completion: nil}))
+      nil
+    end
+
+    # Posts an event to the loop. Safe to call from any thread (including IO threads).
+    #
+    # @param event [Phronomy::Event]
+    # @api private
+    def post(event)
+      @queue.push(event)
+    end
+
+    # Starts the background event loop thread.
+    # @return [self]
+    # @api private
+    def start
+      return self if @thread&.alive?
+
+      # Reset shutdown state so the loop can be restarted after a stop.
+      @shutdown_token = Phronomy::CancellationToken.new
+      @fsm_count_mutex.synchronize { @fsm_count = 0 }
+      @running = true
+      @thread = Thread.new do
+        Thread.current[:phronomy_event_loop_thread] = true
+        run_loop
+      end
+      @thread.abort_on_exception = false
+      self
+    end
+
+    # Stops the background thread. Used in tests only.
+    #
+    # Sends a cooperative shutdown sentinel to the event queue so that the
+    # worker thread can finish any in-flight handler before exiting.  Waits up
+    # to +timeout+ seconds for a clean shutdown; if the thread is still alive
+    # afterwards it is force-killed as a last resort.
+    #
+    # @param timeout [Numeric] seconds to wait for cooperative shutdown. Defaults
+    #   to +Phronomy.configuration.event_loop_stop_grace_seconds+ (5 s).
+    # @param drain [Boolean] when +true+, wait for all active FSMSessions to
+    #   complete before signalling the loop to stop.  Bounded by +timeout+.
+    #   Defaults to +false+.
+    # @param force_kill [Boolean] when +true+, the worker thread is killed with
+    #   +Thread#kill+ if it does not stop within +timeout+. When +false+
+    #   (default), the thread is never killed; the method returns +:timeout+
+    #   instead. +false+ is safer for production because +Thread#kill+ can
+    #   interrupt +ensure+ blocks.
+    # @return [Symbol] shutdown status:
+    #   - +:clean+ — loop exited cooperatively with no active sessions discarded
+    #   - +:drained_with_discards+ — drain mode requested but sessions remained;
+    #     they were discarded and the loop was stopped
+    #   - +:timeout+ — the worker thread did not stop in time and +force_kill:+ is +false+
+    #   - +:force_killed+ — the worker thread did not stop in time and was killed
+    # @api private
+    def stop(timeout: Phronomy.configuration.event_loop_stop_grace_seconds, drain: false, force_kill: false)
+      @shutdown_token.cancel!
+      status = :clean
+
+      if drain
+        # Wait for active sessions to finish, bounded by timeout.
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+        @fsm_count_mutex.synchronize do
+          while @fsm_count > 0
+            remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            break if remaining <= 0
+            @fsm_count_cond.wait(@fsm_count_mutex, remaining)
+          end
+          status = :drained_with_discards if @fsm_count > 0
+        end
+      end
+
+      @running = false
+      @queue.push(:__stop__)   # unblock queue.pop so the worker can see @running = false
+      begin
+        @thread&.join(timeout)
+      rescue
+        # Thread may have terminated with an exception (e.g. simulated crash in
+        # tests). Suppress the re-raise so the cleanup below always runs.
+        nil
+      end
+      if @thread&.alive?
+        if force_kill
+          Phronomy.configuration.logger&.warn(
+            "[Phronomy] EventLoop thread did not stop within #{timeout}s; force-killing. " \
+            "This is a last resort — check for blocking operations in event handlers."
+          )
+          @thread.kill
+          status = :force_killed
+        else
+          Phronomy.configuration.logger&.warn(
+            "[Phronomy] EventLoop thread did not stop within #{timeout}s; abandoning " \
+            "(force_kill: false). Check for blocking operations in event handlers."
+          )
+          status = :timeout
+        end
+      end
+      @thread = nil
+      status
+    end
+
+    private
+
+    def run_loop
+      while @running
+        event = @queue.pop
+        # :__stop__ is used purely as an unblock signal for @queue.pop; the
+        # actual stop condition is @running == false (set before the push).
+        # Treating it as `next` instead of `break` prevents a stale sentinel
+        # (left by a previous stop call that raced with thread start) from
+        # immediately terminating a freshly restarted EventLoop.
+        next if event == :__stop__
+
+        case event.type
+        when :finished, :halted, :error
+          # All three terminal events share the same cleanup path.
+          # Both @fsms and @waiting are exclusively owned by this thread.
+          @fsms.delete(event.target_id)
+          cq = @waiting.delete(event.target_id)
+          cq&.push(event.payload)
+          # Decrement active FSM count and signal drain waiters.
+          @fsm_count_mutex.synchronize do
+            @fsm_count -= 1
+            @fsm_count_cond.signal if @fsm_count <= 0
+          end
+
+        when :start
+          # session and completion_queue arrive together in the payload so that
+          # this thread is the sole writer of @fsms and @waiting.
+          # completion may be nil for fire-and-forget child sessions (AgentFSM).
+          session = event.payload[:session]
+          cq = event.payload[:completion]
+
+          # When shutdown has been requested, reject new sessions with a
+          # CancellationError rather than starting new LLM calls that would
+          # be interrupted by force-kill.
+          if @shutdown_token.cancelled? && cq
+            cq.push(Phronomy::CancellationError.new("EventLoop is shutting down"))
+            next
+          end
+
+          @fsms[event.target_id] = session
+          @waiting[event.target_id] = cq if cq
+          @fsm_count_mutex.synchronize { @fsm_count += 1 }
+          session.start
+
+        else
+          fsm = @fsms[event.target_id]
+          if fsm
+            fsm.handle(event)
+          else
+            # Warn when an event is dropped due to an unknown target_id so that
+            # mis-typed IDs and handler-deregistration races are visible.
+            warn "[Phronomy::EventLoop] Dropped event #{event.type.inspect} — " \
+                 "no handler for target_id #{event.target_id.inspect}"
+          end
+        end
+      end
+    rescue => e
+      # Unblock all waiting callers if the loop dies unexpectedly.
+      @waiting.values.each { |cq| cq.push(e) }
+      raise
+    end
+  end
+end

data/lib/phronomy/fsm_session.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Event-driven execution wrapper for a single workflow run.
+  #
+  # Created by WorkflowRunner and registered with EventLoop. All public methods
+  # are called from the EventLoop thread — FSMSession is NOT thread-safe and must
+  # not be accessed concurrently from multiple threads.
+  #
+  # == Lifecycle
+  #
+  #   register(session) → EventLoop posts :start → session.start
+  #                                 ↓ (auto-transition present)
+  #                        EventLoop posts :state_completed → session.handle
+  #                                 ↓ (repeat)
+  #                        session posts :finished or :halted
+  #                                 ↓
+  #                        EventLoop pushes ctx to completion_queue → caller unblocks
+  #
+  # == Async IO pattern (EventLoop mode only)
+  #
+  # When a state has no auto-transition and is not a wait_state, but has an
+  # external event registered (e.g. +transition from: :fetching, on: :fetch_done+),
+  # the FSMSession stays registered in the EventLoop and waits for that event.
+  # The entry action is expected to spawn an IO thread that posts the event back:
+  #
+  #   entry :fetching, ->(ctx) {
+  #     Thread.new {
+  #       ctx.result = http.get(ctx.url)
+  #       Phronomy::EventLoop.instance.post(
+  #         Phronomy::Event.new(type: :fetch_done, target_id: ctx.thread_id, payload: nil)
+  #       )
+  #     }
+  #   }
+  #   transition from: :fetching, on: :fetch_done, to: :process
+  class FSMSession
+    FINISH = WorkflowRunner::FINISH
+
+    # @return [String] workflow thread_id (matches WorkflowContext#thread_id)
+    attr_reader :id
+
+    # @param id                  [String]
+    # @param context             [Object]        includes Phronomy::WorkflowContext
+    # @param entry_point         [Symbol]        initial state name
+    # @param entry_actions       [Hash]          { state_name => [callable, ...] }
+    # @param auto_state_set      [Hash]          { state_name => true }
+    # @param declared_states     [Array<Symbol>] all action state names
+    # @param wait_state_names    [Array<Symbol>]
+    # @param external_events     [Hash]          { event_name => [{from:, to:, guard:}] }
+    # @param phase_machine_class [Class]         state_machines-backed phase tracker class
+    # @param recursion_limit     [Integer]
+    # @param resume_event        [Symbol, nil]   external event to fire when resuming
+    # @param resume_phase        [Symbol, nil]   wait state name to resume from
+    # @api private
+    def initialize(id:, context:, entry_point:, entry_actions:, auto_state_set:,
+      declared_states:, wait_state_names:, external_events:, phase_machine_class:,
+      recursion_limit:, resume_event: nil, resume_phase: nil)
+      @id = id
+      @ctx = context
+      @entry_point = entry_point
+      @entry_actions = entry_actions
+      @auto_state_set = auto_state_set
+      @declared_states = declared_states
+      @wait_state_names = wait_state_names
+      @external_events = external_events
+      @phase_machine_class = phase_machine_class
+      @recursion_limit = recursion_limit
+      @resume_event = resume_event
+      @resume_phase = resume_phase
+      @step = 0
+      @done = false
+      @current_state = nil
+      @tracker = nil
+    end
+
+    # Begins workflow execution. Called by EventLoop on :start event.
+    def start
+      if @resume_event
+        # Resume from wait state: position tracker at the wait state, then fire the
+        # external event. state_machines fires before_transition (exit) and
+        # after_transition (entry) callbacks, so both actions execute here.
+        @current_state = @resume_phase
+        @tracker = build_tracker(@current_state)
+        @tracker.context = @ctx
+        fire_and_advance!(@resume_event)
+      else
+        # Fresh start: state_machines does not fire callbacks on initialization,
+        # so we invoke the entry action for the initial state manually.
+        @current_state = @entry_point
+        @tracker = build_tracker(@current_state)
+        @tracker.context = @ctx
+        (@entry_actions[@current_state] || []).each do |c|
+          result = c.call(@ctx)
+          @ctx = result if result.is_a?(Phronomy::WorkflowContext)
+        end
+        @tracker.context = @ctx
+        advance_or_halt
+      end
+    rescue => e
+      finish_with_error(e)
+    end
+
+    # Processes an event dispatched from EventLoop.
+    # Called for :state_completed and all user-defined external events.
+    #
+    # @param event [Phronomy::Event]
+    # @api private
+    def handle(event)
+      return if @done
+
+      fire_and_advance!(event.type)
+    rescue => e
+      finish_with_error(e)
+    end
+
+    private
+
+    # Fires event_name on the phase tracker, updates @current_state, then
+    # calls advance_or_halt to decide what to do next.
+    def fire_and_advance!(event_name)
+      if @step >= @recursion_limit
+        raise Phronomy::RecursionLimitError,
+          "Recursion limit (#{@recursion_limit}) exceeded"
+      end
+
+      fire_event!(@tracker, event_name, @current_state)
+      @ctx = @tracker.context
+      next_phase = @tracker.phase.to_sym
+      # When next_phase == @current_state, no transition matched → treat as terminal.
+      @current_state = (next_phase == @current_state) ? FINISH : next_phase
+      @step += 1
+      advance_or_halt
+    end
+
+    # Determines the next action after the FSM has entered @current_state.
+    def advance_or_halt
+      return finish! if @current_state == FINISH
+
+      if @wait_state_names.include?(@current_state)
+        return halt!
+      end
+
+      if @auto_state_set.key?(@current_state)
+        event_loop.post(Event.new(type: :state_completed, target_id: @id, payload: nil))
+        return
+      end
+
+      if has_external_event_from?(@current_state)
+        # Async IO pattern: the entry action spawned an IO thread that will post
+        # an external event back. Stay registered; do nothing here.
+        return
+      end
+
+      # No transition declared — validate the state is known, then treat as terminal.
+      unless @declared_states.include?(@current_state)
+        raise ArgumentError, "State #{@current_state.inspect} is not defined"
+      end
+
+      finish!
+    end
+
+    def finish!
+      @done = true
+      @ctx.set_graph_metadata(thread_id: @id, phase: :__end__)
+      event_loop.post(Event.new(type: :finished, target_id: @id, payload: @ctx))
+    end
+
+    def halt!
+      @done = true
+      @ctx.set_graph_metadata(thread_id: @id, phase: @current_state)
+      event_loop.post(Event.new(type: :halted, target_id: @id, payload: @ctx))
+    end
+
+    def finish_with_error(err)
+      @done = true
+      event_loop.post(Event.new(type: :error, target_id: @id, payload: err))
+    end
+
+    def fire_event!(tracker, event_name, from_state)
+      return if tracker.send(event_name)
+
+      raise ArgumentError,
+        "Transition from #{from_state.inspect} via event #{event_name.inspect} failed. " \
+        "Ensure at least one guard matches or add a fallback (no-guard) transition."
+    end
+
+    def has_external_event_from?(state)
+      @external_events.any? { |_, transitions| transitions.any? { |t| t[:from] == state } }
+    end
+
+    def build_tracker(from_state)
+      machine = @phase_machine_class.new
+      machine.instance_variable_set(:@phase, from_state.to_s)
+      machine
+    end
+
+    def event_loop
+      Phronomy::EventLoop.instance
+    end
+  end
+end

data/lib/phronomy/generator_verifier.rb

@@ -113,6 +113,7 @@ module Phronomy
     # @param raise_if_untrusted    [Boolean] when +true+, raises
     #   {Phronomy::LowConfidenceError} if the final result does not meet the
     #   confidence threshold (default: false)
+    # @api private
     def initialize(
       draft_agent:,
       review_agent:,
@@ -133,7 +134,7 @@ module Phronomy
       @threshold = confidence_threshold.to_f
       @max_iterations = max_iterations.to_i
       @raise_if_untrusted = raise_if_untrusted
-      @compiled_graph = nil
+      @compiled_workflow = nil
     end
 
     # Run the generator-verifier pipeline.
@@ -143,8 +144,9 @@ module Phronomy
     # @return [Result]
     # @raise [Phronomy::LowConfidenceError] when +raise_if_untrusted:+ is +true+
     #   and the result does not meet the confidence threshold
+    # @api private
     def invoke(input, config: {})
-      app = compiled_graph
+      app = compiled_workflow
       state = app.invoke({input: input}, config: config)
       confidence = combined_confidence(state)
       trusted = confidence >= @threshold
@@ -166,8 +168,8 @@ module Phronomy
       [(state.self_score || 0.0).to_f, (state.review_score || 0.0).to_f].min
     end
 
-    def compiled_graph
-      @compiled_graph ||= build_workflow
+    def compiled_workflow
+      @compiled_workflow ||= build_workflow
     end
 
     def build_workflow
@@ -184,42 +186,42 @@ module Phronomy
       Phronomy::Workflow.define(PipelineState) do
         initial :draft
 
-        state :draft, action: ->(state) {
+        state :draft
+        state :review
+        state :finalize
+
+        entry :draft, ->(state) {
           feedback = state.review_notes.last
           prompt = dpb.call(state.input, feedback)
           result = draft_agent.invoke(prompt)
           parsed = drp.call(result[:output])
-          state.merge(
-            draft: parsed[:answer].to_s,
-            self_score: pipeline.__send__(:clamp, parsed[:confidence]),
-            citations: pipeline.__send__(:normalize_citations, parsed[:citations]),
-            iteration: state.iteration + 1
-          )
+          state.draft = parsed[:answer].to_s
+          state.self_score = pipeline.__send__(:clamp, parsed[:confidence])
+          state.citations = pipeline.__send__(:normalize_citations, parsed[:citations])
+          state.iteration = state.iteration + 1
         }
 
-        state :review, action: ->(state) {
+        entry :review, ->(state) {
           prompt = rpb.call(state.input, state.draft, state.citations)
           result = review_agent.invoke(prompt)
           parsed = rrp.call(result[:output])
-          state.merge(
-            review_score: pipeline.__send__(:clamp, parsed[:score]),
-            approved: parsed[:approved] == true,
-            review_notes: parsed[:feedback].to_s
-          )
+          state.review_score = pipeline.__send__(:clamp, parsed[:score])
+          state.approved = parsed[:approved] == true
+          state.review_notes << parsed[:feedback].to_s
         }
 
-        state :finalize, action: ->(state) { state.merge(output: state.draft) }
+        entry :finalize, ->(state) { state.output = state.draft }
 
-        after :draft, to: :review
-        after :finalize, to: :__finish__
+        transition from: :draft, to: :review
+        transition from: :finalize, to: :__finish__
 
-        event :route_review, from: :review,
+        transition from: :review,
           guard: ->(state) {
             confidence = [state.self_score || 0.0, state.review_score || 0.0].min
             (confidence >= threshold && state.approved) || state.iteration >= max_iter
           },
           to: :finalize
-        event :route_review, from: :review, to: :draft
+        transition from: :review, to: :draft
       end
     end
 

data/lib/phronomy/guardrail/base.rb

@@ -17,6 +17,7 @@ module Phronomy
       # Validate the value. Subclasses must implement this method.
       # @param value [Object] the input or output being checked
       # @raise [Phronomy::GuardrailError] if the guardrail rejects the value
+      # @api public
       def check(value)
         raise NotImplementedError, "#{self.class}#check is not implemented"
       end
@@ -24,6 +25,7 @@ module Phronomy
       # Run the check, raising GuardrailError on failure.
       # @param value [Object]
       # @return [Object] the original value (unchanged) when the check passes
+      # @api public
       def run!(value)
         check(value)
         value
@@ -34,6 +36,7 @@ module Phronomy
       # Call inside #check to reject the value.
       # @param reason [String] human-readable rejection reason
       # @raise [Phronomy::GuardrailError]
+      # @api public
       def fail!(reason)
         raise Phronomy::GuardrailError.new(reason, guardrail: self)
       end

data/lib/phronomy/guardrail.rb

@@ -5,4 +5,3 @@
 require_relative "guardrail/base"
 require_relative "guardrail/input_guardrail"
 require_relative "guardrail/output_guardrail"
-require_relative "guardrail/builtin"

data/lib/phronomy/knowledge_source/base.rb

@@ -11,9 +11,12 @@ module Phronomy
     class Base
       # Retrieve knowledge chunks relevant to the given query.
       #
-      # @param query [String, nil] the current user input used to select relevant chunks
+      # @param query              [String, nil]                    the current user input used to select relevant chunks
+      # @param cancellation_token [Phronomy::CancellationToken, nil] optional token; raises CancellationError when cancelled
       # @return [Array<Hash>] array of { content: String, type: Symbol }
-      def fetch(query: nil)
+      # @api public
+      def fetch(query: nil, cancellation_token: nil)
+        cancellation_token&.raise_if_cancelled!
         raise NotImplementedError, "#{self.class}#fetch is not implemented"
       end
 
@@ -24,6 +27,7 @@ module Phronomy
       # Override in subclasses that return fixed content.
       #
       # @return [Boolean]
+      # @api public
       def static?
         false
       end