roast-ai 0.4.9 → 0.5.0

data/lib/roast/dsl/system_cogs/map.rb

@@ -0,0 +1,448 @@
+# typed: true
+# frozen_string_literal: true
+
+module Roast
+  module DSL
+    module SystemCogs
+      # Map cog for executing a scope over a collection of items
+      #
+      # Executes a named execution scope (defined with `execute(:name)`) for each item in a collection.
+      # Supports both serial and parallel execution modes. Each iteration receives the current item
+      # as its value and the iteration index.
+      class Map < SystemCog
+        # Parent class for all `map` cog output access errors
+        class MapOutputAccessError < Roast::Error; end
+
+        # Raised when attempting to access an iteration that did not run
+        #
+        # This can occur when a `break!` is called during iteration, preventing
+        # subsequent iterations from executing.
+        class MapIterationDidNotRunError < MapOutputAccessError; end
+
+        # Configuration for the `map` cog
+        class Config < Cog::Config
+          # Configure the cog to execute iterations in parallel with a maximum number of concurrent tasks
+          #
+          # Pass `0` to enable unlimited parallelism (no concurrency limit).
+          # Pass a positive integer to limit the number of iterations that can run concurrently.
+          #
+          # Default: serial execution (equivalent to `parallel(1)`)
+          #
+          # #### See Also
+          # - `parallel!`
+          # - `no_parallel!`
+          #
+          #: (Integer) -> void
+          def parallel(value)
+            # treat 0 as unlimited parallelism
+            @values[:parallel] = value > 0 ? value : nil
+          end
+
+          # Configure the cog to execute iterations in parallel with unlimited concurrency
+          #
+          # This removes any limit on the number of iterations that can run concurrently.
+          # All iterations will start simultaneously.
+          #
+          # #### See Also
+          # - `parallel`
+          # - `no_parallel!`
+          #
+          #: () -> void
+          def parallel!
+            @values[:parallel] = nil
+          end
+
+          # Configure the cog to execute iterations serially (one at a time)
+          #
+          # This is the default behavior. Iterations will run sequentially in order.
+          #
+          # #### See Also
+          # - `parallel`
+          # - `parallel!`
+          #
+          #: () -> void
+          def no_parallel!
+            @values[:parallel] = 1
+          end
+
+          # Validate the configuration
+          #
+          #: () -> void
+          def validate!
+            valid_parallel!
+          end
+
+          # Get the validated, configured parallelism limit
+          #
+          # Returns `nil` for unlimited parallelism, or an `Integer` for the maximum number
+          # of concurrent iterations. This method will raise an `InvalidConfigError` if the
+          # parallelism value is negative.
+          #
+          # #### See Also
+          # - `parallel`
+          # - `parallel!`
+          # - `no_parallel!`
+          #
+          #: () -> Integer?
+          def valid_parallel!
+            parallel = @values.fetch(:parallel, 1)
+            return if parallel.nil?
+            raise InvalidConfigError, "'parallel' must be >= 0 if specified" if parallel < 0
+
+            parallel
+          end
+        end
+
+        # Parameters for the `map` cog
+        class Params < SystemCog::Params
+          # The name of the execution scope to invoke for each item
+          #
+          #: Symbol
+          attr_accessor :run
+
+          # Initialize parameters with the cog name and execution scope
+          #
+          #: (?Symbol?, run: Symbol) -> void
+          def initialize(name = nil, run:)
+            super(name)
+            @run = run
+          end
+        end
+
+        # Input for the `map` cog
+        #
+        # Provides the collection of items to iterate over and an optional starting index.
+        # Each item will be passed to the execution scope along with its index.
+        class Input < Cog::Input
+          # The collection of items to iterate over
+          #
+          # This can be any enumerable collection. Each item will be passed as the value
+          # to the execution scope. Required.
+          #
+          #: Array[untyped]
+          attr_accessor :items
+
+          # The starting index for the first iteration
+          #
+          # Defaults to `0`. This affects the index value passed to each iteration but does
+          # not change which items are processed.
+          #
+          #: Integer
+          attr_accessor :initial_index
+
+          # Initialize the input with default values
+          #
+          #: () -> void
+          def initialize
+            super
+            @items = []
+            @initial_index = 0
+          end
+
+          # Validate that required input values are present
+          #
+          #: () -> void
+          def validate!
+            raise Cog::Input::InvalidInputError, "'items' is required" if items.nil?
+            raise Cog::Input::InvalidInputError if items.empty? && !coerce_ran?
+          end
+
+          # Coerce the input from the return value of the input block
+          #
+          # Sets the items from the input block's return value if not already set directly.
+          # Converts enumerable objects to arrays and wraps non-enumerable single values in an array.
+          #
+          #: (Array[untyped]) -> void
+          def coerce(input_return_value)
+            super
+            return if @items.present?
+
+            @items = input_return_value.respond_to?(:each) ? input_return_value.to_a : Array.wrap(input_return_value)
+          end
+        end
+
+        # Output from running the `map` cog
+        #
+        # Contains results from each iteration, allowing access to individual iteration outputs.
+        # Iterations that did not run (due to `break!`) will be `nil`.
+        #
+        # #### See Also
+        # - `Roast::DSL::CogInputContext#collect` - retrieves all iteration outputs as an array
+        # - `Roast::DSL::CogInputContext#reduce` - reduces iteration outputs to a single value
+        class Output < Cog::Output
+          # Initialize the output with results for each iteration
+          #
+          #: (Array[ExecutionManager?]) -> void
+          def initialize(execution_managers)
+            super()
+            @execution_managers = execution_managers
+          end
+
+          # Check if a specific iteration ran successfully
+          #
+          # Returns `true` if the iteration at the given index executed, `false` if it was
+          # skipped (e.g., due to `break!`). Supports negative indices to count from the end.
+          #
+          # #### See Also
+          # - `iteration`
+          #
+          #: (Integer) -> bool
+          def iteration?(index)
+            @execution_managers.fetch(index).present?
+          end
+
+          # Get the output from a specific iteration, in concert with `from`
+          #
+          # Returns a `Roast::DSL::SystemCogs::Call::Output` object for the iteration at the given index.
+          # Supports negative indices to count from the end (e.g., `-1` for the last iteration).
+          # Raises `MapIterationDidNotRunError` if the iteration did not run.
+          #
+          # Use `from` on the return value of this method, as for a single `call` cog invocation, to access the
+          # final output and individual cog outputs from the specified invocation.
+          #
+          # #### Usage
+          # ```ruby
+          # # Access a specific iteration
+          # result = from(map!(:process_items).iteration(2))
+          #
+          # # Access with negative index
+          # result = from(map!(:process_items).iteration(-1))
+          # ```
+          #
+          # #### See Also
+          # - `iteration?`
+          # - `first`
+          # - `last`
+          # - `Roast::DSL::CogInputContext#from`
+          #
+          #: (Integer) -> Call::Output
+          def iteration(index)
+            em = @execution_managers.fetch(index)
+            raise MapIterationDidNotRunError, index unless em.present?
+
+            Call::Output.new(em)
+          end
+
+          # Get the output from the first iteration
+          #
+          # Convenience method equivalent to `iteration(0)`. Raises `MapIterationDidNotRunError`
+          # if the first iteration did not run.
+          #
+          # #### See Also
+          # - `iteration`
+          # - `last`
+          #
+          #: () -> Call::Output
+          def first
+            iteration(0)
+          end
+
+          # Get the output from the last iteration that ran
+          #
+          # Convenience method equivalent to `iteration(-1)`. Raises `MapIterationDidNotRunError`
+          # if the last iteration did not run.
+          #
+          # #### See Also
+          # - `iteration`
+          # - `first`
+          #
+          #: () -> Call::Output
+          def last
+            iteration(-1)
+          end
+        end
+
+        # @requires_ancestor: Roast::DSL::ExecutionManager
+        module Manager
+          private
+
+          #: (Params, ^(Cog::Input) -> untyped) -> SystemCogs::Map
+          def create_map_system_cog(params, input_proc)
+            SystemCogs::Map.new(params.name, input_proc) do |input, config|
+              raise ExecutionManager::ExecutionScopeNotSpecifiedError unless params.run.present?
+
+              input = input #: as Input
+              config = config #: as Config
+              max_parallel_tasks = config.valid_parallel!
+              if max_parallel_tasks == 1
+                execute_map_in_series(params.run, input)
+              else
+                execute_map_in_parallel(params.run, input, max_parallel_tasks)
+              end
+            end
+          end
+
+          #: (Symbol, untyped, Integer) -> ExecutionManager
+          def create_execution_manager_for_map_item(scope, scope_value, scope_index)
+            ExecutionManager.new(
+              @cog_registry,
+              @config_manager,
+              @all_execution_procs,
+              @workflow_context,
+              scope:,
+              scope_value:,
+              scope_index:,
+            )
+          end
+
+          #: (Symbol, Map::Input) -> Output
+          def execute_map_in_series(run, input)
+            ems = []
+            input.items.each_with_index do |item, index|
+              ems << em = create_execution_manager_for_map_item(run, item, index + input.initial_index)
+              em.prepare!
+              em.run!
+            rescue ControlFlow::Break
+              # TODO: do something with the message passed to break!
+              break
+            end
+            ems.fill(nil, ems.length, input.items.length - ems.length)
+            Output.new(ems)
+          end
+
+          #: (Symbol, Map::Input, Integer?) -> Output
+          def execute_map_in_parallel(run, input, max_parallel_tasks)
+            barrier = Async::Barrier.new
+            semaphore = Async::Semaphore.new(max_parallel_tasks, parent: barrier) if max_parallel_tasks.present?
+            ems = {}
+            input.items.map.with_index do |item, index|
+              (semaphore || barrier).async(finished: false) do |task|
+                task.annotate("Map Invocation #{index + input.initial_index}")
+                ems[index] = em = create_execution_manager_for_map_item(run, item, index + input.initial_index)
+                em.prepare!
+                em.run!
+              end
+            end #: Array[Async::Task]
+
+            # Wait on the tasks in their completion order, so that an exception in a task will be raised as soon as it occurs
+            # noinspection RubyArgCount
+            barrier.wait do |task|
+              task.wait
+            rescue ControlFlow::Break
+              # TODO: do something with the message passed to break!
+              barrier.stop
+            rescue StandardError => e
+              barrier.stop
+              raise e
+            end
+
+            Output.new((0...input.items.length).map { |idx| ems[idx] })
+          ensure
+            # noinspection RubyRedundantSafeNavigation
+            barrier&.stop
+          end
+        end
+
+        # @requires_ancestor: Roast::DSL::CogInputContext
+        module InputContext
+          # Collect the results from all `map` cog iterations into an array
+          #
+          # Extracts the final output from each iteration that ran. When called without a block,
+          # returns an array of the final outputs directly. When called with a block, executes
+          # the block in the context of each iteration's input context, receiving the final output,
+          # the original item value, and the iteration index as arguments.
+          #
+          # Iterations that did not run (due to `break!`) will be represented as `nil` in the
+          # returned array.
+          #
+          # #### Usage
+          # ```ruby
+          # # Get all final outputs directly
+          # results = collect(map!(:process_items))
+          #
+          # # Transform each output with access to the original item and index
+          # results = collect(map!(:process_items)) do |output, item, index|
+          #   { item: item, result: output, position: index }
+          # end
+          #
+          # # Access other cog outputs from within each iteration
+          # results = collect(map!(:process_items)) do |output, item, index|
+          #   inner_cog!(:some_step)
+          # end
+          # ```
+          #
+          # #### See Also
+          # - `reduce`
+          # - `Roast::DSL::SystemCogs::Map::Output`
+          #
+          # @rbs [T] (Roast::DSL::SystemCogs::Map::Output) {() -> T} -> Array[T]
+          #    | (Roast::DSL::SystemCogs::Map::Output) -> Array[untyped]
+          def collect(map_cog_output, &block)
+            ems = map_cog_output.instance_variable_get(:@execution_managers)
+            raise CogInputContext::ContextNotFoundError if ems.nil?
+
+            return ems.map do |em|
+              next unless em
+
+              scope_value = em.instance_variable_get(:@scope_value)
+              scope_index = em.instance_variable_get(:@scope_index)
+              final_output = em.final_output
+              em.cog_input_context.instance_exec(final_output, scope_value, scope_index, &block)
+            end if block_given?
+
+            ems.map { |em| em&.final_output }
+          end
+
+          # Reduce the results from all `map` cog iterations to a single value
+          #
+          # Processes each iteration's output sequentially, combining them into an accumulator value.
+          # The block receives the current accumulator value, the final output from the iteration,
+          # the original item value, and the iteration index. The block should return the new
+          # accumulator value.
+          #
+          # If the block returns `nil`, the accumulator will __not__ be updated (preserving any
+          # previous non-nil value). This prevents accidental overwrites with `nil` values.
+          #
+          # Iterations that did not run (due to `break!`) are skipped.
+          #
+          # #### Usage
+          # ```ruby
+          # # Sum all outputs
+          # total = reduce(map!(:calculate_scores), 0) do |sum, output, item, index|
+          #   sum + output
+          # end
+          #
+          # # Build a hash from outputs
+          # results = reduce(map!(:process_items), {}) do |hash, output, item, index|
+          #   hash.merge(item => output)
+          # end
+          #
+          # # Collect with conditional accumulation
+          # valid_results = reduce(map!(:validate_items), []) do |acc, output, item, index|
+          #   output.valid? ? acc + [output] : acc
+          # end
+          # ```
+          #
+          # #### See Also
+          # - `collect`
+          # - `Roast::DSL::SystemCogs::Map::Output`
+          #
+          #: [A] (Roast::DSL::SystemCogs::Map::Output, ?A?) {(A?, untyped) -> A} -> A?
+          def reduce(map_cog_output, initial_value = nil, &block)
+            ems = map_cog_output.instance_variable_get(:@execution_managers)
+            raise CogInputContext::ContextNotFoundError if ems.nil?
+
+            accumulator = initial_value
+            ems.compact.each do |em|
+              next unless em
+
+              scope_value = em.instance_variable_get(:@scope_value)
+              scope_index = em.instance_variable_get(:@scope_index)
+              final_output = em.final_output
+              new_accumulator = em.cog_input_context.instance_exec(accumulator, final_output, scope_value, scope_index, &block)
+              case new_accumulator
+              when nil
+                # do not overwrite a non-nil value in the accumulator with a nil value,
+                # even if one is returned from the block
+              else
+                accumulator = new_accumulator #: as A
+              end
+            end
+
+            accumulator
+          end
+        end
+      end
+    end
+  end
+end

data/lib/roast/dsl/system_cogs/repeat.rb

@@ -0,0 +1,242 @@
+# typed: true
+# frozen_string_literal: true
+
+module Roast
+  module DSL
+    module SystemCogs
+      # Repeat cog for executing a scope multiple times in a loop
+      #
+      # Executes a named execution scope (defined with `execute(:name)`) repeatedly until
+      # a `break!` is called. The output from each iteration becomes the input value for
+      # the next iteration, allowing for iterative transformations.
+      class Repeat < SystemCog
+        # Configuration for the `repeat` cog
+        #
+        # Currently has no configuration options.
+        class Config < Cog::Config; end
+
+        # Parameters for the `repeat` cog
+        class Params < SystemCog::Params
+          # The name of the execution scope to invoke for each iteration
+          #
+          #: Symbol
+          attr_accessor :run
+
+          # Initialize parameters with the cog name and execution scope
+          #
+          #: (?Symbol?, run: Symbol) -> void
+          def initialize(name = nil, run:)
+            super(name)
+            @run = run
+          end
+        end
+
+        # Input for the `repeat` cog
+        #
+        # Provides the initial value to pass to the first iteration. Each subsequent iteration
+        # receives the output from the previous iteration as its value.
+        class Input < Cog::Input
+          # The initial value to pass to the first iteration
+          #
+          # This value will be passed to the execution scope on the first iteration. Subsequent
+          # iterations receive the output from the previous iteration. Required.
+          #
+          #: untyped
+          attr_accessor :value
+
+          # The starting index for the first iteration
+          #
+          # Defaults to `0`. This affects the index value passed to each iteration.
+          #
+          # Integer
+          attr_accessor :index
+
+          # The maximum number of iterations for which the loop may run
+          #
+          # Defaults to `nil`, meaning that no maximum iteration limit is applied
+          #
+          #: Integer?
+          attr_accessor :max_iterations
+
+          # Initialize the input with default values
+          #
+          #: () -> void
+          def initialize
+            super
+            @index = 0
+          end
+
+          # Validate that required input values are present
+          #
+          #: () -> void
+          def validate!
+            raise Cog::Input::InvalidInputError, "'value' is required" if value.nil? && !coerce_ran?
+            raise Cog::Input::InvalidInputError, "'max_iterations' must be >= 1 if present" if (max_iterations || 1) < 1
+          end
+
+          # Coerce the input from the return value of the input block
+          #
+          # Sets the value from the input block's return value if not already set directly.
+          #
+          #: (untyped) -> void
+          def coerce(input_return_value)
+            super
+            @value = input_return_value unless @value.present?
+          end
+        end
+
+        # Output from running the `repeat` cog
+        #
+        # Contains results from all iterations that ran. Provides access to the final value
+        # (output from the last iteration) as well as individual iteration results.
+        #
+        # #### See Also
+        # - `Roast::DSL::CogInputContext#collect` - retrieves all iteration outputs as an array (via `results`)
+        # - `Roast::DSL::CogInputContext#reduce` - reduces iteration outputs to a single value (via `results`)
+        class Output < Cog::Output
+          # Initialize the output with results for all iterations
+          #
+          #: (Array[ExecutionManager]) -> void
+          def initialize(execution_managers)
+            super()
+            @execution_managers = execution_managers
+          end
+
+          # Get the final output value from the last iteration
+          #
+          # This is the output from the last iteration before `break!` was called.
+          # Returns `nil` if no iterations ran.
+          #
+          # #### Usage
+          # ```ruby
+          # # Get the final result directly
+          # final = repeat!(:process)
+          # ```
+          #
+          # #### See Also
+          # - `last`
+          # - `results`
+          #
+          #: () -> untyped
+          def value
+            @execution_managers.last&.final_output
+          end
+
+          # Get the output from a specific iteration
+          #
+          # Returns a `Roast::DSL::SystemCogs::Call::Output` object for the iteration at the given index.
+          # Supports negative indices to count from the end (e.g., `-1` for the last iteration).
+          #
+          # #### Usage
+          # ```ruby
+          # # Access a specific iteration
+          # result = from(repeat!(:process).iteration(2))
+          #
+          # # Access with negative index
+          # result = from(repeat!(:process).iteration(-1))
+          # ```
+          #
+          # #### See Also
+          # - `first`
+          # - `last`
+          # - `value`
+          # - `Roast::DSL::CogInputContext#from`
+          #
+          #: (Integer) -> Call::Output
+          def iteration(index)
+            Call::Output.new(@execution_managers.fetch(index))
+          end
+
+          # Get the output from the first iteration
+          #
+          # Convenience method equivalent to `iteration(0)`.
+          #
+          # #### See Also
+          # - `iteration`
+          # - `last`
+          #
+          #: () -> Call::Output
+          def first
+            iteration(0)
+          end
+
+          # Get the output from the last iteration
+          #
+          # Convenience method equivalent to `iteration(-1)`. Returns the same value as
+          # calling `value`, but wrapped in a `Roast::DSL::SystemCogs::Call::Output` for use with `from`.
+          #
+          # #### See Also
+          # - `iteration`
+          # - `first`
+          # - `value`
+          #
+          #: () -> Call::Output
+          def last
+            iteration(-1)
+          end
+
+          # Get all iteration results as a `Roast::DSL::SystemCogs::Map::Output` object
+          #
+          # Returns a `Roast::DSL::SystemCogs::Map::Output` containing all iterations, which can be used with
+          # `collect` or `reduce` to process all iteration outputs.
+          #
+          # #### Usage
+          # ```ruby
+          # # Collect all iteration outputs
+          # all_results = collect(repeat!(:process).results)
+          #
+          # # Reduce all iteration outputs
+          # sum = reduce(repeat!(:process).results, 0) { |acc, output| acc + output }
+          # ```
+          #
+          # #### See Also
+          # - `value`
+          # - `Roast::DSL::CogInputContext#collect`
+          # - `Roast::DSL::CogInputContext#reduce`
+          # - `Roast::DSL::SystemCogs::Map::Output`
+          #
+          #: () -> Map::Output
+          def results
+            Map::Output.new(@execution_managers)
+          end
+        end
+
+        # @requires_ancestor: Roast::DSL::ExecutionManager
+        module Manager
+          private
+
+          #: (Params, ^(Cog::Input) -> untyped) -> SystemCogs::Repeat
+          def create_repeat_system_cog(params, input_proc)
+            SystemCogs::Repeat.new(params.name, input_proc) do |input|
+              input = input #: as Input
+              raise ExecutionManager::ExecutionScopeNotSpecifiedError unless params.run.present?
+
+              ems = [] #: Array[ExecutionManager]
+              scope_value = input.value.deep_dup
+              max_iterations = input.max_iterations
+              loop do
+                ems << em = ExecutionManager.new(
+                  @cog_registry,
+                  @config_manager,
+                  @all_execution_procs,
+                  @workflow_context,
+                  scope: params.run,
+                  scope_value: scope_value,
+                  scope_index: ems.length,
+                )
+                em.prepare!
+                em.run!
+                scope_value = em.final_output
+                break if max_iterations.present? && ems.length >= max_iterations
+              rescue ControlFlow::Break
+                # TODO: do something with the message passed to break!
+                break
+              end
+              Output.new(ems)
+            end
+          end
+        end
+      end
+    end
+  end
+end