phronomy 0.26.0 → 0.28.0

data/lib/phronomy/vector_store/embeddings/ruby_llm_embeddings.rb

@@ -1,47 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module VectorStore
-    module Embeddings
-      # Embeddings adapter backed by RubyLLM.
-      #
-      # Delegates to +RubyLLM.embed+ and returns the resulting vector as an
-      # +Array<Float>+.
-      #
-      # @example Default model
-      #   embeddings = Phronomy::VectorStore::Embeddings::RubyLLMEmbeddings.new
-      #   vector = embeddings.embed("Hello, world!")
-      #
-      # @example Explicit model
-      #   embeddings = Phronomy::VectorStore::Embeddings::RubyLLMEmbeddings.new(model: "text-embedding-3-small")
-      #   vector = embeddings.embed("Hello, world!")
-      class RubyLLMEmbeddings < Base
-        # @param model               [String, nil] embedding model identifier; nil uses the RubyLLM default
-        # @param provider            [Symbol, nil] provider override (e.g. :openai); nil uses the RubyLLM default
-        # @param assume_model_exists [Boolean]     when true, skips RubyLLM model-registry validation
-        #                                          (useful for locally hosted models not in the registry)
-        # @api public
-        def initialize(model: nil, provider: nil, assume_model_exists: false)
-          @model = model
-          @provider = provider
-          @assume_model_exists = assume_model_exists
-        end
-
-        # Embed text via RubyLLM.
-        #
-        # @param text               [String]
-        # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil] optional; raises CancellationError when cancelled
-        # @return [Array<Float>]
-        # @api public
-        def embed(text, cancellation_token = nil)
-          cancellation_token&.raise_if_cancelled!
-          opts = {}
-          opts[:model] = @model if @model
-          opts[:provider] = @provider if @provider
-          opts[:assume_model_exists] = true if @assume_model_exists
-          RubyLLM.embed(text, **opts).vectors
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/workflow/phase_machine_builder.rb

@@ -1,205 +0,0 @@
-# frozen_string_literal: true
-
-require "state_machines"
-
-module Phronomy
-  class Workflow
-    # Builds the anonymous state-machine Class used by WorkflowRunner.
-    #
-    # This class compiles Workflow topology into state_machines declarations.
-    # It intentionally does not await Tasks, register completion callbacks,
-    # cancel external work, or interpret application event payloads.
-    #
-    # @api private
-    class PhaseMachineBuilder
-      def initialize(
-        entry_point:,
-        declared_states:,
-        wait_state_names:,
-        external_events:,
-        entry_actions:,
-        auto_transitions:,
-        exit_actions:
-      )
-        @entry_point = entry_point
-        @declared_states = declared_states
-        @wait_state_names = wait_state_names
-        @external_events = external_events
-        @entry_actions = entry_actions
-        @auto_transitions = auto_transitions
-        @exit_actions = exit_actions
-      end
-
-      def build
-        entry = @entry_point
-        all_states = (@declared_states + @wait_state_names + [:__end__]).uniq
-        auto_transitions = @auto_transitions
-        external_events = @external_events
-        entry_actions = @entry_actions
-        exit_actions = @exit_actions
-        condition_builder = method(:build_transition_condition)
-        entry_callback_builder = method(:build_entry_callback)
-        exit_callback_builder = method(:build_exit_callback)
-        transition_callback = build_transition_action_callback
-
-        Class.new do
-          attr_accessor(
-            :context,
-            :current_event,
-            :selected_transition_action,
-            :selected_transition_metadata
-          )
-
-          state_machine :phase, initial: entry do
-            all_states.each { |state_name| state state_name }
-
-            event :state_completed do
-              auto_transitions.each do |transition_definition|
-                transition(
-                  transition_definition[:from] => transition_definition[:to],
-                  :if => condition_builder.call(transition_definition)
-                )
-              end
-            end
-
-            external_events.each do |event_name, transitions|
-              event event_name do
-                transitions.each do |transition_definition|
-                  transition(
-                    transition_definition[:from] => transition_definition[:to],
-                    :if => condition_builder.call(transition_definition)
-                  )
-                end
-              end
-            end
-
-            entry_actions.each do |state_name, callables|
-              callables.each do |callable|
-                after_transition(
-                  to: state_name,
-                  &entry_callback_builder.call(callable, state_name)
-                )
-              end
-            end
-
-            # Both source exit callbacks and the transition action are
-            # before_transition callbacks. Register exits first to preserve the
-            # required exit -> transition action -> entry ordering.
-            exit_actions.each do |state_name, callables|
-              callables.each do |callable|
-                before_transition(
-                  from: state_name,
-                  &exit_callback_builder.call(callable, state_name)
-                )
-              end
-            end
-
-            before_transition(&transition_callback)
-          end
-        end
-      rescue => error
-        raise ArgumentError, "Failed to build phase machine: #{error.message}"
-      end
-
-      private
-
-      def build_transition_condition(transition_definition)
-        guard = transition_definition[:guard]
-        action = transition_definition[:action]
-        metadata = {
-          from: transition_definition[:from],
-          event: transition_definition[:event],
-          to: public_destination(transition_definition[:to])
-        }.freeze
-
-        ->(machine) {
-          matched =
-            guard.nil? ||
-            call_with_optional_event(
-              guard,
-              machine.context,
-              machine.current_event
-            )
-
-          if matched
-            machine.selected_transition_action = action
-            machine.selected_transition_metadata = metadata
-          end
-          matched
-        }
-      end
-
-      def build_transition_action_callback
-        ->(machine) {
-          callable = machine.selected_transition_action
-          unless callable.nil?
-            metadata = machine.selected_transition_metadata || {}
-            result = call_with_optional_event(
-              callable,
-              machine.context,
-              machine.current_event
-            )
-            if result.is_a?(Phronomy::TaskResult)
-              raise Phronomy::InvalidAsyncTransitionActionError,
-                transition_task_error_message(metadata)
-            end
-            machine.context = result if workflow_context_result?(result)
-          end
-        }
-      end
-
-      def build_entry_callback(callable, state_name)
-        ->(machine) {
-          result = callable.call(machine.context)
-          if result.is_a?(Phronomy::TaskResult)
-            raise Phronomy::InvalidAsyncEntryActionError,
-              "Entry action for state #{state_name.inspect} returned Phronomy::TaskResult. " \
-              "Start the asynchronous operation, register its callback/listener, " \
-              "and return the WorkflowContext or nil."
-          end
-          machine.context = result if workflow_context_result?(result)
-        }
-      end
-
-      def build_exit_callback(callable, state_name)
-        ->(machine) {
-          result = callable.call(machine.context)
-          if result.is_a?(Phronomy::TaskResult)
-            raise Phronomy::InvalidAsyncEntryActionError,
-              "Exit action for state #{state_name.inspect} returned Phronomy::TaskResult. " \
-              "Exit actions are synchronous Run-to-Completion callbacks."
-          end
-        }
-      end
-
-      def call_with_optional_event(callable, context, event)
-        parameters =
-          if callable.respond_to?(:parameters)
-            callable.parameters
-          else
-            callable.method(:call).parameters
-          end
-        accepts_event = parameters.length >= 2
-        accepts_event ? callable.call(context, event) : callable.call(context)
-      end
-
-      def workflow_context_result?(result)
-        result.respond_to?(:set_graph_metadata)
-      end
-
-      def public_destination(destination)
-        return :__finish__ if destination == Phronomy::WorkflowRunner::FINISH
-
-        destination
-      end
-
-      def transition_task_error_message(metadata)
-        "Transition action " \
-          "#{metadata[:from].inspect} --#{metadata[:event].inspect}--> " \
-          "#{metadata[:to].inspect} returned Phronomy::TaskResult. " \
-          "Start the asynchronous operation, register its callback/listener, " \
-          "and return the WorkflowContext or nil."
-      end
-    end
-  end
-end

data/lib/phronomy/workflow_recovery.rb

@@ -1,123 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  # ACS-15 Workflow-side Persistence F1 reconciliation. Workflow hydration and
-  # orchestration remain owned by WorkflowRunner; this module only replaces the
-  # terminal durable barrier so response loss is reconciled from authoritative
-  # durable pre/post state instead of being treated as an ordinary failed save.
-  # @api private
-  module WorkflowRecovery
-    private
-
-    def begin_terminal_persistence_on_event_loop(
-      execution,
-      terminal_type:,
-      context:,
-      event_sink:
-    )
-      runtime = Phronomy::Runtime.instance
-      event_loop = runtime.event_loop
-      assert_event_loop!(event_loop)
-      event_loop.mark_workflow_admission(
-        execution.workflow_instance_id,
-        owner_token: execution.owner_token,
-        state: :persisting_terminal
-      )
-
-      operation = Phronomy::WorkflowRunner::WorkflowTerminalPersistenceCommand.new(
-        repository: execution.repository,
-        workflow_instance_id: execution.workflow_instance_id.to_s.freeze,
-        expected_revision: execution.expected_revision,
-        snapshot: deep_immutable_copy(snapshot_for(context))
-      )
-
-      task = runtime.offload.submit(on_full: :raise) do
-        revision = operation.repository.save(
-          operation.workflow_instance_id,
-          expected_revision: operation.expected_revision,
-          snapshot: operation.snapshot
-        )
-        Phronomy::WorkflowRunner::WorkflowTerminalPersistenceResult.new(
-          outcome: :success,
-          revision: revision,
-          error: nil
-        )
-      rescue Phronomy::Persistence::ConflictError,
-        Phronomy::Persistence::NotFoundError,
-        Phronomy::Persistence::SerializationError,
-        Phronomy::Persistence::UnsupportedBackendError => error
-        Phronomy::WorkflowRunner::WorkflowTerminalPersistenceResult.new(
-          outcome: :known_failure,
-          revision: nil,
-          error: error
-        )
-      rescue => error
-        reconcile_workflow_terminal_f1(operation, error)
-      end
-
-      task.on_complete do |result, operation_error|
-        delivery = if operation_error
-          Phronomy::WorkflowRunner::WorkflowTerminalPersistenceResult.new(
-            outcome: :outcome_unknown,
-            revision: nil,
-            error: operation_error
-          )
-        else
-          result
-        end
-        accepted = event_sink.post(:workflow_terminal_persistence_result, delivery)
-        unless accepted
-          Phronomy.configuration.logger&.warn(
-            "[Phronomy] EventLoop rejected Workflow terminal persistence result " \
-            "for #{execution.workflow_instance_id.inspect}"
-          )
-        end
-      end
-      terminal_type
-    end
-
-    def reconcile_workflow_terminal_f1(operation, original_error)
-      record = operation.repository.load(operation.workflow_instance_id)
-      case Phronomy::Recovery.compare_revisioned_snapshot(
-        record: record,
-        expected_pre_revision: operation.expected_revision,
-        intended_snapshot: operation.snapshot
-      )
-      when :post_state
-        revision = Phronomy::Recovery.fetch_value(record, :revision)
-        Phronomy::WorkflowRunner::WorkflowTerminalPersistenceResult.new(
-          outcome: :success,
-          revision: revision,
-          error: nil
-        )
-      when :pre_state
-        # The uncertain save is now known not to have committed. Do not blindly
-        # retry it here; surface a known failure through the ordinary terminal
-        # barrier semantics.
-        Phronomy::WorkflowRunner::WorkflowTerminalPersistenceResult.new(
-          outcome: :known_failure,
-          revision: nil,
-          error: original_error
-        )
-      else
-        conflict = Phronomy::Persistence::ConflictError.new(
-          "Workflow terminal Persistence outcome conflicts with both expected " \
-          "pre-state and intended post-state for #{operation.workflow_instance_id.inspect}"
-        )
-        Phronomy::WorkflowRunner::WorkflowTerminalPersistenceResult.new(
-          outcome: :outcome_unknown,
-          revision: nil,
-          error: conflict
-        )
-      end
-    rescue => reconciliation_error
-      Phronomy::WorkflowRunner::WorkflowTerminalPersistenceResult.new(
-        outcome: :outcome_unknown,
-        revision: nil,
-        error: reconciliation_error
-      )
-    end
-  end
-end
-
-Phronomy::WorkflowRunner.prepend(Phronomy::WorkflowRecovery)

data/sig/phronomy/llm_adapter.rbs

@@ -1,11 +0,0 @@
-module Phronomy
-  module LLMAdapter
-    class Base
-      def complete: (untyped chat, String? message, ?config: Hash[untyped, untyped]) -> untyped
-      def stream: (untyped chat, String? message, ?config: Hash[untyped, untyped]) { (untyped chunk) -> void } -> untyped
-    end
-
-    class RubyLLM < Base
-    end
-  end
-end

data/sig/phronomy/runtime.rbs

@@ -1,76 +0,0 @@
-module Phronomy
-  class TaskResult[A]
-    class Outcome[V]
-      attr_reader index: Integer
-      attr_reader status: (:completed | :failed | :cancelled | :unfinished)
-      attr_reader value: V?
-      attr_reader error: Exception?
-    end
-
-    def self.completed: [V] (V value, ?name: String?) -> TaskResult[V]
-                      | (?name: String?) -> TaskResult[nil]
-    def self.failed: (Exception error, ?name: String?) -> TaskResult[untyped]
-    def self.all_settled: [V] (Array[TaskResult[V]] results) -> TaskResult[Array[Outcome[V]]]
-    attr_reader name: String?
-    attr_reader parent: TaskResult[untyped]?
-
-    def status: () -> (:pending | :completed | :failed | :cancelled)
-    def done?: () -> bool
-    def alive?: () -> bool
-    def wait_result: (?timeout: Numeric?) -> A
-    def on_complete: () { (A?, Exception?) -> void } -> self
-    def map: [B] () { (A) -> B } -> TaskResult[B]
-    def flat_map: [B] () { (A) -> TaskResult[B] } -> TaskResult[B]
-  end
-
-  class Execution
-    attr_reader invocation_context: InvocationContext
-
-    def self.run_async: [I, V] (Array[I] inputs, ?timeout: Numeric?, ?cancellation_token: Concurrency::CancellationToken?, ?invocation_context: InvocationContext?) { (I, Execution) -> TaskResult[V] } -> TaskResult[Array[TaskResult::Outcome[V]]]
-    def self.run: [I, V] (Array[I] inputs, ?timeout: Numeric?, ?cancellation_token: Concurrency::CancellationToken?, ?invocation_context: InvocationContext?) { (I, Execution) -> TaskResult[V] } -> Array[TaskResult::Outcome[V]]
-    def observe: [V] (TaskResult[V] source_result) -> TaskResult[V]
-  end
-
-  class ExecutionTimeoutError < TimeoutError
-    attr_reader outcomes: Array[TaskResult::Outcome[untyped]]
-    def initialize: (?String message, outcomes: Array[TaskResult::Outcome[untyped]]) -> void
-  end
-
-  class ExecutionCancellationError < CancellationError
-    attr_reader outcomes: Array[TaskResult::Outcome[untyped]]
-    def initialize: (?String message, outcomes: Array[TaskResult::Outcome[untyped]]) -> void
-  end
-
-  module Concurrency
-    class CancellationToken
-      def self.timeout_after: (Numeric seconds) -> CancellationToken
-      def initialize: (?monotonic_deadline: Float?) -> void
-      def remaining_monotonic_seconds: () -> Float?
-      def on_cancel: () { () -> void } -> self
-      def cancel!: () -> self
-      def cancelled?: () -> bool
-      def raise_if_cancelled!: (?String message) -> nil
-    end
-  end
-end
-
-module Phronomy
-  class InvocationContext
-    attr_reader user_id: String?
-    attr_reader cancellation_token: Concurrency::CancellationToken?
-    attr_reader deadline: untyped
-    attr_reader token_budget: Integer?
-    attr_reader approval_policy: untyped
-    attr_reader redaction_policy: untyped
-    attr_reader task_id: String?
-    attr_reader parent_task_id: String?
-
-    def initialize: (?user_id: String?, ?cancellation_token: Concurrency::CancellationToken?, ?deadline: untyped, ?token_budget: Integer?, ?approval_policy: untyped, ?redaction_policy: untyped, ?task_id: String?, ?parent_task_id: String?) -> void
-  end
-end
-
-module Phronomy
-  module Blocking
-    def self.call_async: [V] (?timeout: Numeric?, ?cancellation_token: Concurrency::CancellationToken?, ?invocation_context: InvocationContext?) { () -> V } -> TaskResult[V]
-  end
-end