phronomy 0.6.0 → 0.7.0

data/lib/phronomy/tracing/open_telemetry_tracer.rb

@@ -17,6 +17,7 @@ module Phronomy
     #   end
     class OpenTelemetryTracer < Base
       # @param tracer_name [String] name passed to the OTel TracerProvider
+      # @api public
       def initialize(tracer_name: "phronomy")
         require "opentelemetry"
         @otel_tracer = OpenTelemetry.tracer_provider.tracer(tracer_name, Phronomy::VERSION)
@@ -27,6 +28,7 @@ module Phronomy
       # +phronomy.+.
       #
       # @return [OpenTelemetry::Trace::Span]
+      # @api public
       def start_span(name, input: nil, **attributes)
         attrs = {}
         attrs["phronomy.input"] = input.to_s if input

data/lib/phronomy/vector_store/base.rb

@@ -9,25 +9,32 @@ module Phronomy
     class Base
       # Add a document with its vector embedding.
       #
-      # @param id        [String]  unique document identifier
-      # @param embedding [Array<Float>] vector embedding
-      # @param metadata  [Hash]    arbitrary metadata (e.g. the original message object)
-      def add(id:, embedding:, metadata: {})
+      # @param id                 [String]                         unique document identifier
+      # @param embedding          [Array<Float>]                   vector embedding
+      # @param metadata           [Hash]                           arbitrary metadata (e.g. the original message object)
+      # @param cancellation_token [Phronomy::CancellationToken, nil] optional; raises CancellationError when cancelled
+      # @api public
+      def add(id:, embedding:, metadata: {}, cancellation_token: nil)
+        cancellation_token&.raise_if_cancelled!
         raise NotImplementedError, "#{self.class}#add is not implemented"
       end
 
       # Return the k most similar documents to the query embedding.
       #
-      # @param query_embedding [Array<Float>]
-      # @param k               [Integer]       number of results
+      # @param query_embedding    [Array<Float>]
+      # @param k                  [Integer]                        number of results
+      # @param cancellation_token [Phronomy::CancellationToken, nil] optional; raises CancellationError when cancelled
       # @return [Array<Hash>] each element: { id:, score:, metadata: }
-      def search(query_embedding:, k: 5)
+      # @api public
+      def search(query_embedding:, k: 5, cancellation_token: nil)
+        cancellation_token&.raise_if_cancelled!
         raise NotImplementedError, "#{self.class}#search is not implemented"
       end
 
       # Remove a single document by id.
       #
       # @param id [String] document identifier
+      # @api public
       def remove(id:)
         raise NotImplementedError, "#{self.class}#remove is not implemented"
       end
@@ -37,6 +44,14 @@ module Phronomy
         raise NotImplementedError, "#{self.class}#clear is not implemented"
       end
 
+      # Return the number of documents stored.
+      #
+      # @return [Integer]
+      # @api public
+      def size
+        raise NotImplementedError, "#{self.class}#size is not implemented"
+      end
+
       private
 
       # Validates that embedding has the expected dimension.
@@ -51,6 +66,17 @@ module Phronomy
         raise ArgumentError,
           "Embedding dimension mismatch: expected #{expected_dimension}, got #{actual}"
       end
+
+      # Validates that k is a positive integer.
+      # Accepts any value accepted by Integer() (e.g. "5"), but raises
+      # ArgumentError for non-integer strings, zero, and negative values.
+      def validate_k!(k)
+        int_k = Integer(k)
+        raise ArgumentError, "k must be a positive integer, got #{int_k}" unless int_k >= 1
+        int_k
+      rescue ArgumentError => e
+        raise ArgumentError, "k must be a positive integer: #{e.message}"
+      end
     end
   end
 end

data/lib/phronomy/vector_store/in_memory.rb

@@ -16,15 +16,19 @@ module Phronomy
       #   When nil, the dimension is inferred from the first call to #add.
       #   For multi-threaded use, pass dimension: explicitly; concurrent first
       #   adds are not guaranteed to be race-free.
+      # @api public
       def initialize(dimension: nil)
         @documents = {}
         @expected_dimension = dimension
       end
 
-      # @param id        [String]
-      # @param embedding [Array<Float>]
-      # @param metadata  [Hash]
-      def add(id:, embedding:, metadata: {})
+      # @param id                 [String]
+      # @param embedding          [Array<Float>]
+      # @param metadata           [Hash]
+      # @param cancellation_token [Phronomy::CancellationToken, nil]
+      # @api public
+      def add(id:, embedding:, metadata: {}, cancellation_token: nil)
+        cancellation_token&.raise_if_cancelled!
         # Establish expected dimension on first add, then validate.
         @expected_dimension ||= embedding.size
         validate_embedding_dimension!(embedding, @expected_dimension)
@@ -32,10 +36,14 @@ module Phronomy
         self
       end
 
-      # @param query_embedding [Array<Float>]
-      # @param k               [Integer]
+      # @param query_embedding    [Array<Float>]
+      # @param k                  [Integer]
+      # @param cancellation_token [Phronomy::CancellationToken, nil]
       # @return [Array<Hash>] sorted by descending score
-      def search(query_embedding:, k: 5)
+      # @api public
+      def search(query_embedding:, k: 5, cancellation_token: nil)
+        cancellation_token&.raise_if_cancelled!
+        k = validate_k!(k)
         # search never establishes dimension; validate only when dimension is known.
         validate_embedding_dimension!(query_embedding, @expected_dimension)
         # Take an atomic snapshot before iterating.  Hash#dup is a C-level
@@ -62,6 +70,7 @@ module Phronomy
       end
 
       # @return [Integer] number of documents stored
+      # @api public
       def size
         @documents.size
       end

data/lib/phronomy/vector_store/pgvector.rb

@@ -22,6 +22,7 @@ module Phronomy
       # @param dimension   [Integer, nil] expected embedding dimension for Phronomy-side
       #   pre-validation.  When nil, dimension enforcement is delegated to the
       #   database schema; no pre-validation is performed by Phronomy.
+      # @api public
       def initialize(model_class:, dimension: nil)
         begin
           require "pgvector"
@@ -34,10 +35,13 @@ module Phronomy
         @dimension = dimension
       end
 
-      # @param id        [String]
-      # @param embedding [Array<Float>]
-      # @param metadata  [Hash]
-      def add(id:, embedding:, metadata: {})
+      # @param id                 [String]
+      # @param embedding          [Array<Float>]
+      # @param metadata           [Hash]
+      # @param cancellation_token [Phronomy::CancellationToken, nil]
+      # @api public
+      def add(id:, embedding:, metadata: {}, cancellation_token: nil)
+        cancellation_token&.raise_if_cancelled!
         validate_embedding_dimension!(embedding, @dimension)
         @model_class.upsert(
           {id: id, embedding: safe_vector(embedding), metadata: metadata.to_json},
@@ -46,13 +50,16 @@ module Phronomy
         self
       end
 
-      # @param query_embedding [Array<Float>]
-      # @param k               [Integer]
+      # @param query_embedding    [Array<Float>]
+      # @param k                  [Integer]
+      # @param cancellation_token [Phronomy::CancellationToken, nil]
       # @return [Array<Hash>] sorted by descending similarity score
-      def search(query_embedding:, k: 5)
+      # @api public
+      def search(query_embedding:, k: 5, cancellation_token: nil)
+        cancellation_token&.raise_if_cancelled!
+        k_safe = validate_k!(k)
         validate_embedding_dimension!(query_embedding, @dimension)
         vec = safe_vector_literal(query_embedding)
-        k_safe = Integer(k)
         conn = @model_class.connection
         quoted_vec = "#{conn.quote(vec)}::vector"
 
@@ -64,7 +71,7 @@ module Phronomy
             {
               id: r.id.to_s,
               score: r.score.to_f,
-              metadata: JSON.parse(r.metadata.to_s, symbolize_names: true)
+              metadata: parse_metadata(r.metadata)
             }
           end
       end
@@ -79,8 +86,32 @@ module Phronomy
         self
       end
 
+      # Returns the number of documents in the backing table.
+      def size
+        @model_class.count
+      end
+
       private
 
+      # Parses a metadata value returned by the pg driver.
+      # Handles NULL (nil), already-parsed Hash, and JSON string forms.
+      def parse_metadata(raw)
+        return {} if raw.nil?
+        return symbolize_hash_keys(raw) if raw.is_a?(Hash)
+
+        parsed = JSON.parse(raw.to_s, symbolize_names: true)
+        parsed.is_a?(Hash) ? parsed : {}
+      rescue JSON::ParserError
+        {}
+      end
+
+      # Recursively symbolizes keys for an already-parsed Hash.
+      def symbolize_hash_keys(hash)
+        hash.each_with_object({}) do |(k, v), h|
+          h[k.to_sym] = v.is_a?(Hash) ? symbolize_hash_keys(v) : v
+        end
+      end
+
       # Validates that all elements are numeric and converts to a pgvector-
       # compatible literal string (e.g. "[1.0,0.5,-0.3]").
       def safe_vector_literal(embedding)

data/lib/phronomy/vector_store/redis_search.rb

@@ -30,6 +30,7 @@ module Phronomy
       #   dimension: explicitly.  Without it, a freshly constructed instance
       #   treats the index as uninitialized until #add is called, and #search
       #   silently returns [] in the meantime.
+      # @api public
       def initialize(redis:, index_name: "phronomy_vectors", dimension: nil)
         begin
           require "redis"
@@ -45,10 +46,13 @@ module Phronomy
         @mutex = Mutex.new
       end
 
-      # @param id        [String]
-      # @param embedding [Array<Float>]
-      # @param metadata  [Hash]
-      def add(id:, embedding:, metadata: {})
+      # @param id                 [String]
+      # @param embedding          [Array<Float>]
+      # @param metadata           [Hash]
+      # @param cancellation_token [Phronomy::CancellationToken, nil]
+      # @api public
+      def add(id:, embedding:, metadata: {}, cancellation_token: nil)
+        cancellation_token&.raise_if_cancelled!
         # Establish expected dimension on first add (not race-free for concurrent
         # first adds), then validate, then create/reuse the index.
         @dimension ||= embedding.size
@@ -62,17 +66,20 @@ module Phronomy
         self
       end
 
-      # @param query_embedding [Array<Float>]
-      # @param k               [Integer]
+      # @param query_embedding    [Array<Float>]
+      # @param k                  [Integer]
+      # @param cancellation_token [Phronomy::CancellationToken, nil]
       # @return [Array<Hash>] sorted by descending similarity score
-      def search(query_embedding:, k: 5)
+      # @api public
+      def search(query_embedding:, k: 5, cancellation_token: nil)
+        cancellation_token&.raise_if_cancelled!
         # search never establishes dimension.  If dimension is unknown and the
         # index has not been created yet, there are no documents to return.
         return [] if @dimension.nil? && !@index_created
 
         validate_embedding_dimension!(query_embedding, @dimension)
         ensure_index!(@dimension)
-        k_safe = Integer(k)
+        k_safe = validate_k!(k)
         blob = pack_vector(query_embedding)
 
         raw = @redis.call(
@@ -92,6 +99,20 @@ module Phronomy
         self
       end
 
+      # Returns the number of documents indexed.
+      # Queries FT.INFO when the index has been created; returns 0 otherwise.
+      def size
+        return 0 unless @index_created
+
+        raw = @redis.call("FT.INFO", @index_name)
+        return 0 unless raw.is_a?(Array)
+
+        idx = raw.index("num_docs")
+        idx ? raw[idx + 1].to_i : 0
+      rescue
+        0
+      end
+
       def clear
         @mutex.synchronize do
           begin

data/lib/phronomy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Phronomy
-  VERSION = "0.6.0"
+  VERSION = "0.7.0"
 end

data/lib/phronomy/workflow.rb

@@ -59,15 +59,21 @@ module Phronomy
 
     # Defines a new Workflow.
     # @param context_class [Class] class that includes Phronomy::WorkflowContext
+    # @param state_store [Phronomy::StateStore::Base, nil] optional per-workflow state store.
+    #   Takes precedence over the global +Phronomy.configuration.state_store+.
     # @yield block evaluated in DSL context
     # @return [Phronomy::Workflow] compiled and ready-to-run workflow instance
-    def self.define(context_class, &block)
-      builder = Builder.new(context_class)
+    # @raise [ArgumentError] if no states are declared (empty workflow)
+    # @raise [ArgumentError] if any transition references an undeclared +to:+ or +from:+ state
+    # @api public
+    def self.define(context_class, state_store: nil, &block)
+      builder = Builder.new(context_class, state_store: state_store)
       builder.instance_eval(&block)
       builder.build
     end
 
     # @param runner [Phronomy::WorkflowRunner]
+    # @api public
     def initialize(runner)
       @runner = runner
     end
@@ -76,6 +82,7 @@ module Phronomy
     # @param input [Hash] initial context field values
     # @param config [Hash] { thread_id:, recursion_limit:, user_id:, session_id: }
     # @return [Object] final context
+    # @api public
     def invoke(input, config: {})
       @runner.invoke(input, config: config)
     end
@@ -84,6 +91,7 @@ module Phronomy
     # @param state [Object] halted context
     # @param input [Hash, nil] optional field updates to merge before resuming
     # @return [Object] final context
+    # @api public
     def resume(state:, input: nil)
       @runner.resume(state: state, input: input)
     end
@@ -93,6 +101,7 @@ module Phronomy
     # @param event [Symbol] event name (e.g. :approve, :reject, :resume)
     # @param input [Hash, nil] optional field updates to merge before resuming
     # @return [Object] final context
+    # @api public
     def send_event(state:, event:, input: nil)
       @runner.send_event(state: state, event: event, input: input)
     end
@@ -102,6 +111,7 @@ module Phronomy
     # @param config [Hash]
     # @yield [Hash]
     # @return [Object] final context
+    # @api public
     def stream(input, config: {}, &block)
       @runner.stream(input, config: config, &block)
     end
@@ -115,8 +125,9 @@ module Phronomy
     class Builder
       FINISH = Phronomy::WorkflowRunner::FINISH
 
-      def initialize(context_class)
+      def initialize(context_class, state_store: nil)
         @context_class = context_class
+        @state_store = state_store
         @initial = nil
         # Ordered list of declared state names (action states only, not wait states).
         @declared_states = []
@@ -133,6 +144,7 @@ module Phronomy
       # Declares the initial (entry) state.
       # @param state_name [Symbol]
       # rubocop:disable Style/TrivialAccessors
+      # @api public
       def initial(state_name)
         @initial = state_name
       end
@@ -143,6 +155,7 @@ module Phronomy
       # @param action [#call, nil] optional entry action shorthand.
       #   +state :generate, action: MY_PROC+ is equivalent to
       #   +state :generate; entry :generate, MY_PROC+.
+      # @api public
       def state(name, action: nil)
         @declared_states << name
         entry(name, action) if action
@@ -150,11 +163,15 @@ module Phronomy
 
       # Declares an entry action for a state.
       # The callable is invoked when the workflow enters +name+.
-      # It receives the current context and should mutate it in place.
-      # Return value is ignored.
+      # It receives the current context. Two styles are supported:
+      #   - Mutation-in-place: mutate context fields directly (+s.field = value+);
+      #     the return value is ignored.
+      #   - Immutable update: return a new context via +s.merge(field: value)+;
+      #     the returned context replaces the current one.
       # Multiple calls for the same state are allowed; callables fire in declaration order.
       # @param name [Symbol] state name
-      # @param callable [#call] receives context, mutates it in place
+      # @param callable [#call] receives context; may return a new WorkflowContext
+      # @api public
       def entry(name, callable)
         (@entry_actions[name] ||= []) << callable
       end
@@ -166,6 +183,7 @@ module Phronomy
       # Multiple calls for the same state are allowed; callables fire in declaration order.
       # @param name [Symbol] state name
       # @param callable [#call] receives context, mutates it in place
+      # @api public
       def exit(name, callable)
         (@exit_actions[name] ||= []) << callable
       end
@@ -173,6 +191,7 @@ module Phronomy
       # Declares a wait state that automatically halts execution when reached.
       # No entry action is registered; the workflow pauses here until an event resumes it.
       # @param name [Symbol] wait state name (conventionally :awaiting_something)
+      # @api public
       def wait_state(name)
         @wait_state_names << name
       end
@@ -188,16 +207,85 @@ module Phronomy
       # @param to [Symbol] destination state or :__finish__
       # @param guard [Proc, nil] optional guard — receives context, returns truthy/falsy
       # @param on [Symbol, nil] named event for manual triggers (e.g. :approve)
+      # @api public
       def transition(from:, to:, guard: nil, on: nil)
         dest = (to == :__finish__) ? FINISH : to
         @transitions << {from: from, to: dest, guard: guard, on: on}
       end
 
+      private
+
+      # Performs build-time structural validation of the workflow graph.
+      # Raises ArgumentError for hard errors; warns for unreachable states.
+      def validate_graph!
+        all_states = (@declared_states + @wait_state_names).uniq
+        entry_point = @initial || @declared_states.first
+
+        if entry_point.nil?
+          raise ArgumentError, "Workflow has no states declared — call state(...) or wait_state(...) at least once"
+        end
+
+        # Collect all reachable state names from transitions (excluding :__finish__ sentinel).
+        referenced_targets = @transitions.map { |t| t[:to] }.reject { |t| t == FINISH }
+        undefined = referenced_targets - all_states
+        unless undefined.empty?
+          raise ArgumentError,
+            "Workflow transition(s) reference undefined state(s): #{undefined.sort.inspect}. " \
+            "Declare each with state(...) or wait_state(...)."
+        end
+
+        # Check that all from: states in transitions are declared.
+        referenced_sources = @transitions.map { |t| t[:from] }
+        undefined_sources = referenced_sources - all_states
+        unless undefined_sources.empty?
+          raise ArgumentError,
+            "Workflow transition(s) originate from undefined state(s): #{undefined_sources.sort.inspect}. " \
+            "Declare each with state(...) or wait_state(...)."
+        end
+
+        # Reachability check: warn about declared states that cannot be reached
+        # from the initial state (transition target not referenced by any transition).
+        reachable = Set.new([entry_point])
+        queue = [entry_point]
+        until queue.empty?
+          current = queue.shift
+          @transitions.each do |t|
+            next if t[:from] != current
+            next if t[:to] == FINISH
+            unless reachable.include?(t[:to])
+              reachable.add(t[:to])
+              queue << t[:to]
+            end
+          end
+        end
+
+        unreachable = all_states - reachable.to_a
+        unless unreachable.empty?
+          msg = "[Phronomy] Workflow has unreachable state(s): #{unreachable.sort.inspect}. " \
+                "These states can never be entered from the initial state '#{entry_point}'."
+          if Phronomy.configuration.logger
+            Phronomy.configuration.logger.warn(msg)
+          else
+            warn msg
+          end
+        end
+      end
+
+      public
+
       # Builds and returns a Phronomy::Workflow backed by a WorkflowRunner.
+      # Performs build-time validation of the graph structure:
+      #   - raises ArgumentError when no initial state is declared and no states have been defined
+      #   - raises ArgumentError when a transition references an undeclared target state
+      #   - warns when declared states are unreachable from the initial state
+      # @raise [ArgumentError] on structural errors
+      # @api public
       def build
         entry_actions = @entry_actions.dup
         exit_actions = @exit_actions.dup
 
+        validate_graph!
+
         # Auto-fire transitions (no :on): fire automatically when action completes.
         # External events (with :on): triggered manually via send_event.
         auto_transitions = []
@@ -220,7 +308,8 @@ module Phronomy
           auto_transitions: auto_transitions,
           external_events: external_events,
           entry_point: @initial || @declared_states.first,
-          wait_state_names: @wait_state_names
+          wait_state_names: @wait_state_names,
+          state_store: @state_store
         )
 
         Workflow.new(runner)

data/lib/phronomy/workflow_context.rb

@@ -11,7 +11,7 @@ module Phronomy
   # Field update policies:
   #   :replace (default) -- overwrites with the new value
   #   :append            -- appends to an Array
-  #   :merge             -- deep-merges into a Hash
+  #   :merge             -- shallow-merges into a Hash (top-level keys are merged; nested objects are replaced)
   #
   # @example
   #   class ScanContext
@@ -31,7 +31,16 @@ module Phronomy
       # @param name [Symbol]
       # @param type [Symbol] :replace / :append / :merge
       # @param default [Object, Proc, nil]
+      # @raise [ArgumentError] if +default+ is a plain Array or Hash (use a Proc instead)
+      # @api public
       def field(name, type: :replace, default: nil)
+        if default.is_a?(Array) || default.is_a?(Hash)
+          raise ArgumentError,
+            "Mutable default for field #{name.inspect} must be wrapped in a Proc " \
+            "to avoid shared state across instances. " \
+            "Use `default: -> { #{default.inspect} }` instead."
+        end
+
         @fields[name] = {type: type, default: default}
         attr_accessor name
       end
@@ -51,12 +60,14 @@ module Phronomy
     #   :awaiting_<name>   — halted at a wait_state(:awaiting_<name>) declaration
     #   :<state>           — resuming at <state> (workflow paused before its execution)
     # @return [Symbol]
+    # @api public
     def phase
       @phase || :__end__
     end
 
     # Returns true if the workflow is paused mid-execution (not yet completed).
     # @return [Boolean]
+    # @api public
     def halted?
       phase != :__end__
     end
@@ -64,6 +75,7 @@ module Phronomy
     # Sets internal workflow metadata. Returns self.
     # @param thread_id [String, nil]
     # @param phase [Symbol, nil]
+    # @api public
     def set_graph_metadata(thread_id: nil, phase: nil)
       @thread_id = thread_id unless thread_id.nil?
       @phase = phase unless phase.nil?
@@ -71,6 +83,9 @@ module Phronomy
     end
 
     def initialize(**attrs)
+      unknown = attrs.keys - self.class.fields.keys
+      raise ArgumentError, "Unknown WorkflowContext field(s): #{unknown.inspect}" unless unknown.empty?
+
       self.class.fields.each do |name, config|
         default = config[:default].is_a?(Proc) ? config[:default].call : config[:default]
         send(:"#{name}=", attrs.fetch(name, default))
@@ -79,11 +94,19 @@ module Phronomy
       @phase = :__end__
     end
 
-    # Immutably updates context fields. Returns a new instance with the applied changes.
-    # Internal workflow metadata (thread_id, phase) is preserved.
+    # Returns a new context instance with the specified field updates applied.
+    # Updated fields follow the field's declared +:type+ semantics (:replace, :append,
+    # or :merge). Unchanged fields are deep-copied on a best-effort basis — objects
+    # that do not support +#dup+ (e.g. integers, frozen objects) are carried over
+    # by reference. Internal workflow metadata (thread_id, phase) is preserved.
     # @param updates [Hash] { field_name => new_value }
     # @return [self.class] new context instance
+    # @raise [ArgumentError] if updates contains keys that are not declared fields
+    # @api public
     def merge(updates)
+      unknown = updates.keys - self.class.fields.keys
+      raise ArgumentError, "Unknown WorkflowContext field(s): #{unknown.inspect}" unless unknown.empty?
+
       new_attrs = {}
       self.class.fields.each_key do |name|
         field_config = self.class.fields[name]
@@ -97,7 +120,7 @@ module Phronomy
             updates[name]
           end
         else
-          send(name)
+          deep_dup_value(send(name))
         end
       end
       new_context = self.class.new(**new_attrs)
@@ -110,10 +133,37 @@ module Phronomy
 
     # Converts user-defined fields to a Hash (excludes internal workflow metadata).
     # @return [Hash]
+    # @api public
     def to_h
       self.class.fields.keys.each_with_object({}) do |name, h|
         h[name] = send(name)
       end
     end
+
+    private
+
+    # Performs a deep copy of a value for immutable context propagation.
+    # Arrays and Hashes are deep-duplicated recursively.
+    # Immutable values (nil, Symbol, Integer, Float, true/false, frozen String) are returned as-is.
+    # Other objects are dup'd (best-effort shallow copy for custom types).
+    # Objects that cannot be dup'd (e.g. Proc, Method) are returned as-is.
+    def deep_dup_value(val)
+      case val
+      when Array
+        val.map { |v| deep_dup_value(v) }
+      when Hash
+        val.each_with_object({}) { |(k, v), h| h[k] = deep_dup_value(v) }
+      when NilClass, Symbol, Integer, Float, TrueClass, FalseClass
+        val
+      else
+        return val if val.frozen?
+
+        begin
+          val.dup
+        rescue TypeError
+          val
+        end
+      end
+    end
   end
 end