phronomy 0.6.0 → 0.7.0

data/lib/phronomy/event_loop.rb

@@ -37,8 +37,14 @@ module Phronomy
 
     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
+      @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.
@@ -53,6 +59,7 @@ module Phronomy
     #
     # @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,
@@ -78,6 +85,7 @@ module Phronomy
     #
     # @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}))
@@ -87,13 +95,20 @@ module Phronomy
     # 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
@@ -104,11 +119,73 @@ module Phronomy
     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
+    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
-      @thread&.kill
+      @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
@@ -116,6 +193,12 @@ module Phronomy
     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
@@ -124,18 +207,42 @@ module Phronomy
           @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).
-          @fsms[event.target_id] = event.payload[:session]
+          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
-          event.payload[:session].start
+          @fsm_count_mutex.synchronize { @fsm_count += 1 }
+          session.start
 
         else
-          @fsms[event.target_id]&.handle(event)
+          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

data/lib/phronomy/fsm_session.rb

@@ -51,6 +51,7 @@ module Phronomy
     # @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)
@@ -88,7 +89,11 @@ module Phronomy
         @current_state = @entry_point
         @tracker = build_tracker(@current_state)
         @tracker.context = @ctx
-        (@entry_actions[@current_state] || []).each { |c| c.call(@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
@@ -99,6 +104,7 @@ module Phronomy
     # Called for :state_completed and all user-defined external events.
     #
     # @param event [Phronomy::Event]
+    # @api private
     def handle(event)
       return if @done
 
@@ -118,6 +124,7 @@ module Phronomy
       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

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:,
@@ -143,6 +144,7 @@ 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_workflow
       state = app.invoke({input: input}, config: config)

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/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

data/lib/phronomy/knowledge_source/entity_knowledge.rb

@@ -43,6 +43,7 @@ module Phronomy
       # Call this after saving a new set of messages (e.g. from a ConversationManager save hook).
       #
       # @param messages [Array] message objects responding to #role and #content
+      # @api public
       def update(messages:)
         messages.each do |msg|
           next unless msg.role.to_sym == :user
@@ -54,9 +55,12 @@ module Phronomy
       # Returns a single chunk containing all known entity facts in XML context format.
       # Returns an empty array when no entities have been discovered.
       #
-      # @param query [String, nil] unused — entity knowledge is always fully injected
+      # @param query              [String, nil]                    unused — entity knowledge is always fully injected
+      # @param cancellation_token [Phronomy::CancellationToken, nil] optional; raises CancellationError when cancelled
       # @return [Array<Hash>]
-      def fetch(query: nil)
+      # @api public
+      def fetch(query: nil, cancellation_token: nil)
+        cancellation_token&.raise_if_cancelled!
         return [] if @entities.empty?
 
         lines = @entities.map { |key, value| "- #{key}: #{value}" }.join("\n")
@@ -70,6 +74,7 @@ module Phronomy
       # Returns the current entity store (primarily for testing).
       #
       # @return [Hash]
+      # @api public
       def entities
         @entities.dup
       end

data/lib/phronomy/knowledge_source/rag_knowledge.rb

@@ -22,6 +22,7 @@ module Phronomy
       # @param type       [Symbol]                         semantic tag (default :rag)
       # @param source     [String, nil]                    default source label; falls back to
       #   each document's :source metadata when nil
+      # @api public
       def initialize(store:, embeddings:, k: 5, type: :rag, source: nil)
         @store = store
         @embeddings = embeddings
@@ -34,13 +35,16 @@ module Phronomy
       #
       # Returns an empty array when query is nil or blank.
       #
-      # @param query [String, nil]
+      # @param query              [String, nil]
+      # @param cancellation_token [Phronomy::CancellationToken, nil] optional; raises CancellationError when cancelled
       # @return [Array<Hash>]
-      def fetch(query: nil)
+      # @api public
+      def fetch(query: nil, cancellation_token: nil)
+        cancellation_token&.raise_if_cancelled!
         return [] if query.nil? || query.strip.empty?
 
-        vector = @embeddings.embed(query)
-        results = @store.search(query_embedding: vector, k: @k)
+        vector = @embeddings.embed(query, cancellation_token)
+        results = @store.search(query_embedding: vector, k: @k, cancellation_token: cancellation_token)
         results.map do |doc|
           chunk = {content: doc[:metadata][:content], type: @type}
           src = @source || doc[:metadata][:source]

data/lib/phronomy/knowledge_source/static_knowledge.rb

@@ -19,6 +19,7 @@ module Phronomy
       # @param source [String, nil] label identifying where this knowledge came from
       #   (e.g. a filename). Included in the context XML tag and exposed to the LLM
       #   so that agents can produce grounded citations.
+      # @api public
       def initialize(text, type: :static, source: nil)
         @text = text.to_s
         @type = type
@@ -27,9 +28,12 @@ module Phronomy
 
       # Returns the fixed text as a single chunk, regardless of query.
       #
-      # @param query [String, nil] ignored for static knowledge
+      # @param query              [String, nil]                    ignored for static knowledge
+      # @param cancellation_token [Phronomy::CancellationToken, nil] optional; raises CancellationError when cancelled
       # @return [Array<Hash>]
-      def fetch(query: nil)
+      # @api public
+      def fetch(query: nil, cancellation_token: nil)
+        cancellation_token&.raise_if_cancelled!
         return [] if @text.empty?
 
         chunk = {content: @text, type: @type}
@@ -39,6 +43,7 @@ module Phronomy
 
       # Static knowledge content never changes between invocations.
       # @return [true]
+      # @api public
       def static?
         true
       end

data/lib/phronomy/loader/base.rb

@@ -16,6 +16,7 @@ module Phronomy
       # @param source [String] file path, URL, or other source identifier
       # @return [Array<Hash>] array of <tt>{ text: String, metadata: Hash }</tt>
       # @raise [NotImplementedError] when not overridden by a subclass
+      # @api public
       def load(source)
         raise NotImplementedError, "#{self.class}#load is not implemented"
       end

data/lib/phronomy/loader/csv_loader.rb

@@ -20,6 +20,7 @@ module Phronomy
     class CsvLoader < Base
       # @param headers     [Boolean] treat the first row as headers (default: true)
       # @param text_column [String, nil] if set, use only this column as the document text
+      # @api public
       def initialize(headers: true, text_column: nil)
         @headers = headers
         @text_column = text_column
@@ -28,6 +29,7 @@ module Phronomy
       # @param source [String] path to a CSV file
       # @return [Array<Hash>]
       # @raise [Errno::ENOENT] if the file does not exist
+      # @api public
       def load(source)
         rows = CSV.read(source, headers: @headers, encoding: "UTF-8")
 

data/lib/phronomy/loader/markdown_loader.rb

@@ -24,6 +24,7 @@ module Phronomy
       HEADING_RE = /^(\#{1,6})\s+(.+)$/
 
       # @param split_on_headings [Boolean] split on H1–H6 boundaries (default: true)
+      # @api public
       def initialize(split_on_headings: true)
         @split_on_headings = split_on_headings
       end
@@ -31,6 +32,7 @@ module Phronomy
       # @param source [String] path to a Markdown file
       # @return [Array<Hash>]
       # @raise [Errno::ENOENT] if the file does not exist
+      # @api public
       def load(source)
         content = File.read(source, encoding: "UTF-8")
         return [{text: content, metadata: {source: source}}] unless @split_on_headings

data/lib/phronomy/loader/plain_text_loader.rb

@@ -12,6 +12,7 @@ module Phronomy
       # @param source [String] absolute or relative path to a text file
       # @return [Array<Hash>] single-element array with the file contents
       # @raise [Errno::ENOENT] if the file does not exist
+      # @api public
       def load(source)
         text = File.read(source, encoding: "UTF-8")
         [{text: text, metadata: {source: source}}]

data/lib/phronomy/output_parser/base.rb

@@ -9,6 +9,7 @@ module Phronomy
 
       # @param input [String, #to_s] text to parse
       # @return [Object] parsed result
+      # @api public
       def invoke(input, config: {})
         parse(input.is_a?(String) ? input : input.to_s)
       end

data/lib/phronomy/output_parser/json_parser.rb

@@ -10,6 +10,7 @@ module Phronomy
       # @param text [String]
       # @return [Hash, Array] result parsed with symbolize_names: true
       # @raise [Phronomy::ParseError] raised when JSON parsing fails
+      # @api public
       def parse(text)
         json_str = extract_json(text)
         JSON.parse(json_str, symbolize_names: true)
@@ -19,10 +20,28 @@ module Phronomy
 
       private
 
-      # Extracts the inner content of a Markdown code fence if present;
-      # otherwise returns the text as-is.
+      # Extracts a JSON string from the LLM response text.
+      #
+      # Strategy (in order):
+      #   1. Try each ```json ... ``` or ``` ... ``` code fence in document order,
+      #      returning the content of the first one that parses as valid JSON.
+      #   2. Try the raw text stripped of leading/trailing whitespace.
+      #
+      # This handles:
+      #   - Single JSON code fence (common case)
+      #   - Multiple code fences — the first parseable JSON block wins
+      #   - No fence — LLM omitted the backticks but returned valid JSON
       def extract_json(text)
-        text.match(/```(?:json)?\s*\n?(.*?)\n?```/m)&.captures&.first || text.strip
+        text.scan(/```(?:json)?\s*\n?(.*?)\n?```/m).each do |captures|
+          candidate = captures.first.strip
+          JSON.parse(candidate)
+          return candidate
+        rescue JSON::ParserError
+          next
+        end
+
+        # Fallback: no valid fence found — try the raw text
+        text.strip
       end
     end
   end

data/lib/phronomy/output_parser/structured_parser.rb

@@ -9,6 +9,7 @@ module Phronomy
     #   parser.parse('{"name":"Alice","age":30}')  #=> #<struct PersonSchema name="Alice", age=30>
     class StructuredParser < Base
       # @param schema_class [Class] Struct with keyword_init: true or equivalent
+      # @api public
       def initialize(schema_class)
         @schema_class = schema_class
       end
@@ -16,6 +17,7 @@ module Phronomy
       # @param text [String]
       # @return [Object] instance of schema_class
       # @raise [Phronomy::ParseError] raised when JSON parsing or schema instantiation fails
+      # @api public
       def parse(text)
         data = JsonParser.new.parse(text)
         @schema_class.new(**data)

data/lib/phronomy/prompt_template.rb

@@ -27,6 +27,7 @@ module Phronomy
 
     # @param template        [String] human message template with {{var}} placeholders
     # @param system_template [String, nil] optional system message template
+    # @api public
     def initialize(template:, system_template: nil)
       @template = template
       @system_template = system_template
@@ -36,6 +37,7 @@ module Phronomy
     #
     # @param variables [Hash{Symbol => String}]
     # @return [String]
+    # @api public
     def format(**variables)
       substitute(@template, variables)
     end
@@ -45,6 +47,7 @@ module Phronomy
     #
     # @param variables [Hash{Symbol => String}]
     # @return [String, nil]
+    # @api public
     def format_system(**variables)
       @system_template && substitute(@system_template, variables)
     end
@@ -54,6 +57,7 @@ module Phronomy
     #
     # @param input  [Hash{Symbol => String}]
     # @return [Hash]
+    # @api public
     def invoke(input, config: {})
       vars = normalize_input(input)
       result = {prompt: format(**vars)}
@@ -65,6 +69,7 @@ module Phronomy
     # Returns the list of placeholder names found in both templates.
     #
     # @return [Array<Symbol>]
+    # @api public
     def variables
       names = @template.scan(PLACEHOLDER).flatten
       names += @system_template.scan(PLACEHOLDER).flatten if @system_template

data/lib/phronomy/runnable.rb

@@ -25,13 +25,30 @@ module Phronomy
     # Yields a span; the block must return [result, usage] where usage is a
     # Phronomy::TokenUsage or nil. Returns only the result value.
     #
+    # When +trace_pii+ is disabled, both the input and the output (LLM response,
+    # tool result) are replaced with the literal string "[REDACTED]" before being
+    # forwarded to the tracing backend. The actual result is still returned to
+    # the caller — only the copy sent to the tracer is redacted.
+    #
     # @example
     #   trace("my_chain", input: input) { [invoke(input), nil] }
+    # @api public
     def trace(name, input: nil, **meta, &block)
-      # Redact user input from spans when trace_pii is disabled to prevent
-      # accidental PII transmission to external tracing backends.
       traced_input = Phronomy.configuration.trace_pii ? input : "[REDACTED]"
-      Phronomy.configuration.tracer.trace(name, input: traced_input, **meta, &block)
+
+      if Phronomy.configuration.trace_pii
+        # PII recording is allowed: pass through unchanged.
+        Phronomy.configuration.tracer.trace(name, input: traced_input, **meta, &block)
+      else
+        # Redact both input (above) and output before forwarding to the tracer.
+        # Capture the real result so callers receive the unredacted value.
+        real_result = nil
+        Phronomy.configuration.tracer.trace(name, input: traced_input, **meta) do |span|
+          real_result, usage = block.call(span)
+          ["[REDACTED]", usage]
+        end
+        real_result
+      end
     end
   end
 end

data/lib/phronomy/splitter/base.rb

@@ -18,6 +18,7 @@ module Phronomy
       #   returned by a Loader, or a plain String.
       # @return [Array<Hash>] array of <tt>{ text: String, metadata: Hash }</tt>
       # @raise [NotImplementedError] when not overridden by a subclass
+      # @api public
       def split(document)
         raise NotImplementedError, "#{self.class}#split is not implemented"
       end
@@ -26,6 +27,7 @@ module Phronomy
       #
       # @param documents [Array<Hash, String>]
       # @return [Array<Hash>]
+      # @api public
       def split_all(documents)
         documents.flat_map { |doc| split(doc) }
       end

data/lib/phronomy/splitter/fixed_size_splitter.rb

@@ -15,6 +15,7 @@ module Phronomy
       # @param chunk_size    [Integer] maximum characters per chunk (default: 1000)
       # @param chunk_overlap [Integer] characters to repeat at the start of each
       #   subsequent chunk (default: 200); must be less than chunk_size
+      # @api public
       def initialize(chunk_size: 1000, chunk_overlap: 200)
         raise ArgumentError, "chunk_overlap must be less than chunk_size" if chunk_overlap >= chunk_size
 
@@ -24,6 +25,7 @@ module Phronomy
 
       # @param document [Hash, String]
       # @return [Array<Hash>]
+      # @api public
       def split(document)
         doc = normalise(document)
         text = doc[:text]

data/lib/phronomy/splitter/recursive_splitter.rb

@@ -25,6 +25,7 @@ module Phronomy
       # @param chunk_size    [Integer] maximum characters per chunk (default: 1000)
       # @param chunk_overlap [Integer] overlap characters (default: 200)
       # @param separators    [Array<String>] separator list in priority order
+      # @api public
       def initialize(chunk_size: 1000, chunk_overlap: 200, separators: DEFAULT_SEPARATORS)
         raise ArgumentError, "chunk_overlap must be less than chunk_size" if chunk_overlap >= chunk_size
 
@@ -35,6 +36,7 @@ module Phronomy
 
       # @param document [Hash, String]
       # @return [Array<Hash>]
+      # @api public
       def split(document)
         doc = normalise(document)
         texts = recursive_split(doc[:text], @separators)

data/lib/phronomy/state_store/base.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module StateStore
+    # Abstract base class for workflow state persistence backends.
+    #
+    # Subclasses must implement {#load}, {#save}, and {#delete}.
+    # A snapshot is a plain +Hash+ with two keys:
+    #   +:fields+ — output of +context.to_h+
+    #   +:phase+  — +context.phase.to_s+
+    #
+    # @example Implementing a custom backend
+    #   class MyStore < Phronomy::StateStore::Base
+    #     def load(thread_id) = MyRecord.find_by(thread_id:)&.to_h
+    #     def save(thread_id, snapshot) = MyRecord.upsert(thread_id:, data: snapshot)
+    #     def delete(thread_id) = MyRecord.where(thread_id:).delete_all
+    #   end
+    class Base
+      # Load the stored snapshot for +thread_id+.
+      #
+      # @param thread_id [String]
+      # @return [Hash, nil] stored snapshot hash, or +nil+ if absent
+      # @api public
+      def load(thread_id)
+        raise NotImplementedError, "#{self.class}#load is not implemented"
+      end
+
+      # Persist +snapshot+ for +thread_id+. Overwrites any existing snapshot.
+      #
+      # @param thread_id [String]
+      # @param snapshot [Hash] serialisable hash of workflow state
+      # @return [void]
+      # @api public
+      def save(thread_id, snapshot)
+        raise NotImplementedError, "#{self.class}#save is not implemented"
+      end
+
+      # Delete the stored snapshot for +thread_id+. No-op if absent.
+      #
+      # @param thread_id [String]
+      # @return [void]
+      # @api public
+      def delete(thread_id)
+        raise NotImplementedError, "#{self.class}#delete is not implemented"
+      end
+    end
+  end
+end