phronomy 0.6.0 → 0.7.1

data/lib/phronomy/vector_store/base.rb

@@ -6,28 +6,42 @@ module Phronomy
     #
     # Implementations manage a collection of (embedding, metadata) pairs and
     # support similarity search.
+    #
+    # Async methods (`search_async`, `add_async`, `remove_async`, `clear_async`)
+    # are provided by the {AsyncBackend} mixin which defaults to routing calls
+    # through {BlockingAdapterPool}.  Backends with native async drivers may
+    # override individual async methods without touching the pool at all.
     class Base
+      include AsyncBackend
+
       # 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 +51,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 +73,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.1"
 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
@@ -75,15 +81,40 @@ module Phronomy
     # Executes the workflow from the initial state.
     # @param input [Hash] initial context field values
     # @param config [Hash] { thread_id:, recursion_limit:, user_id:, session_id: }
+    # @param invocation_context [Phronomy::InvocationContext, nil] optional first-class context
+    #   object.  When present, +thread_id+, +cancellation_token+, and +deadline+ are
+    #   derived from it (existing +config:+ keys take precedence).  The object is also
+    #   stored in +config[:invocation_context]+ for downstream tracing.
     # @return [Object] final context
-    def invoke(input, config: {})
+    # @api public
+    def invoke(input, config: {}, invocation_context: nil)
+      if invocation_context
+        config = _apply_invocation_context(config, invocation_context)
+      end
       @runner.invoke(input, config: config)
     end
 
+    # Invokes this workflow asynchronously and returns a {Phronomy::Task}.
+    #
+    # @param input  [Hash]
+    # @param config [Hash]
+    # @param invocation_context [Phronomy::InvocationContext, nil]
+    # @return [Phronomy::Task]
+    # @api public
+    def invoke_async(input, config: {}, invocation_context: nil)
+      if invocation_context
+        config = _apply_invocation_context(config, invocation_context)
+      end
+      Phronomy::Runtime.instance.spawn(name: "workflow-invoke-async") do
+        invoke(input, config: config)
+      end
+    end
+
     # Resumes a halted workflow. Generic resume that works for all halt types.
     # @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 +124,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,10 +134,28 @@ 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
 
+    private
+
+    # Merges an {InvocationContext} into the config hash.
+    # Existing +config+ keys take precedence (backward-compat).
+    def _apply_invocation_context(config, ic)
+      effective = config.merge(invocation_context: ic)
+      effective = effective.merge(thread_id: ic.thread_id) if effective[:thread_id].nil? && ic.thread_id
+      if effective[:cancellation_token].nil?
+        if (tok = ic.effective_timeout_token)
+          effective = effective.merge(cancellation_token: tok)
+        end
+      end
+      effective
+    end
+
+    public
+
     # ---------------------------------------------------------------------------
     # Internal DSL builder
     # ---------------------------------------------------------------------------
@@ -115,8 +165,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 = []
@@ -128,33 +179,45 @@ module Phronomy
         @transitions = []
         # Set of wait state names
         @wait_state_names = []
+        # { state_name => Numeric } — per-state action timeout in seconds
+        @action_timeouts = {}
       end
 
       # Declares the initial (entry) state.
       # @param state_name [Symbol]
       # rubocop:disable Style/TrivialAccessors
+      # @api public
       def initial(state_name)
         @initial = state_name
       end
       # rubocop:enable Style/TrivialAccessors
 
       # Declares an action state.
-      # @param name   [Symbol]   state name
-      # @param action [#call, nil] optional entry action shorthand.
+      # @param name           [Symbol]        state name
+      # @param action         [#call, nil]    optional entry action shorthand.
       #   +state :generate, action: MY_PROC+ is equivalent to
       #   +state :generate; entry :generate, MY_PROC+.
-      def state(name, action: nil)
+      # @param action_timeout [Numeric, nil]  seconds before an async (Task-returning)
+      #   entry action is cancelled and {Phronomy::ActionTimeoutError} is raised.
+      #   Only applies when the action returns a {Task} or {PendingOperation}.
+      # @api public
+      def state(name, action: nil, action_timeout: nil)
         @declared_states << name
+        @action_timeouts[name] = action_timeout if action_timeout
         entry(name, action) if action
       end
 
       # 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 +229,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 +237,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 +253,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 +354,9 @@ 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,
+          action_timeouts: @action_timeouts.dup
         )
 
         Workflow.new(runner)