ruby_slm 0.1.0

data/lib/ruby_slm/errors.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module StatesLanguageMachine
+  class Error < StandardError; end
+
+  class ExecutionError < Error
+    # @return [String] the name of the state where the error occurred
+    attr_reader :state_name
+    # @return [String] the cause of the error
+    attr_reader :cause
+
+    # @param state_name [String] the name of the state where the error occurred
+    # @param cause [String] the cause of the error
+    def initialize(state_name, cause)
+      @state_name = state_name
+      @cause = cause
+      super("Execution failed in state '#{state_name}': #{cause}")
+    end
+  end
+
+  class DefinitionError < Error; end
+  class StateNotFoundError < Error; end
+  class TimeoutError < Error; end
+end

data/lib/ruby_slm/execution.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module StatesLanguageMachine
+  class Execution
+    # @return [String, nil] the current state name
+    attr_accessor :current_state
+    # @return [Hash] the current output data
+    attr_accessor :output
+    # @return [Symbol] the execution status (:running, :succeeded, :failed)
+    attr_accessor :status
+    # @return [String, nil] the error type if execution failed
+    attr_accessor :error
+    # @return [String, nil] the cause of failure if execution failed
+    attr_accessor :cause
+    # @return [Array<Hash>] the execution history
+    attr_accessor :history
+    # @return [Logger, nil] the logger for execution
+    attr_accessor :logger
+    # @return [Hash] the execution context
+    attr_accessor :context
+    # @return [Time, nil] the execution end time
+    attr_accessor :end_time
+
+    # @return [StateMachine] the state machine being executed
+    attr_reader :state_machine
+    # @return [Hash] the original input data
+    attr_reader :input
+    # @return [String] the execution name
+    attr_reader :name
+    # @return [Time] the execution start time
+    attr_reader :start_time
+
+    # @param state_machine [StateMachine] the state machine to execute
+    # @param input [Hash] the input data for the execution
+    # @param name [String, nil] the name of the execution
+    # @param context [Hash] additional context for the execution
+    def initialize(state_machine, input = {}, name = nil, context = {})
+      @state_machine = state_machine
+      @input = input.dup
+      @name = name || "execution-#{Time.now.to_i}-#{SecureRandom.hex(4)}"
+      @current_state = state_machine.start_state
+      @output = input.dup
+      @status = :running
+      @history = []
+      @logger = context[:logger]
+      @context = context
+      @start_time = Time.now
+      @end_time = nil
+    end
+
+    # Run the entire execution to completion
+    # @return [Execution] self
+    def run_all
+      while @status == :running && @current_state
+        run_next
+      end
+      self
+    end
+
+    # Run the next state in the execution
+    # @return [Execution] self
+    def run_next
+      return self unless @status == :running && @current_state
+
+      state = @state_machine.get_state(@current_state)
+
+      begin
+        logger&.info("Executing state: #{@current_state}")
+
+        # Execute the current state
+        @output = state.execute(self, @output)
+
+        # Check if the state set the execution to failed
+        if @status == :failed
+          logger&.info("Execution failed in state: #{@current_state}")
+          @end_time ||= Time.now
+          return self
+        end
+
+        # Determine next state - for choice states, we need to pass the output
+        next_state = state.next_state_name(@output)
+
+        logger&.info("State #{@current_state} completed. Next state: #{next_state}")
+
+        if state.end_state?
+          @status = :succeeded unless @status == :failed
+          @current_state = nil
+          @end_time = Time.now
+          logger&.info("Execution completed successfully")
+        elsif next_state
+          @current_state = next_state
+          logger&.info("Moving to next state: #{next_state}")
+        else
+          @status = :failed
+          @error = "NoNextState"
+          @cause = "State '#{@current_state}' has no next state and is not an end state"
+          @end_time = Time.now
+          logger&.error("Execution failed: #{@cause}")
+        end
+
+      rescue => e
+        @status = :failed
+        @error = e.is_a?(ExecutionError) ? e.cause : "ExecutionError"
+        @cause = e.message
+        @end_time = Time.now
+        logger&.error("Execution failed in state #{@current_state}: #{e.message}")
+        logger&.error(e.backtrace.join("\n")) if logger
+      end
+
+      self
+    end
+
+    # Update the execution output
+    # @param new_output [Hash] the new output data
+    def update_output(new_output)
+      @output = new_output
+    end
+
+    # Add an entry to the execution history
+    # @param state_name [String] the name of the state that was executed
+    # @param output [Hash] the output from the state execution
+    def add_history_entry(state_name, output)
+      @history << {
+        state_name: state_name,
+        input: @output, # Current input before execution
+        output: output,
+        timestamp: Time.now
+      }
+    end
+
+    # @return [Boolean] whether the execution succeeded
+    def succeeded?
+      @status == :succeeded
+    end
+
+    # @return [Boolean] whether the execution failed
+    def failed?
+      @status == :failed
+    end
+
+    # @return [Boolean] whether the execution is still running
+    def running?
+      @status == :running
+    end
+
+    # @return [Float] the total execution time in seconds
+    def execution_time
+      return @end_time - @start_time if @end_time
+      Time.now - @start_time
+    end
+
+    # @return [Hash] the execution details as a Hash
+    def to_h
+      {
+        name: @name,
+        status: @status,
+        current_state: @current_state,
+        input: @input,
+        output: @output,
+        error: @error,
+        cause: @cause,
+        start_time: @start_time,
+        end_time: @end_time,
+        execution_time: execution_time,
+        history: @history
+      }
+    end
+
+    # @return [String] the execution details as JSON
+    def to_json
+      JSON.pretty_generate(to_h)
+    end
+  end
+end

data/lib/ruby_slm/state.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module StatesLanguageMachine
+  # Base state class that provides common functionality for all states
+  class State
+    # @return [String] the name of the state
+    attr_reader :name
+    # @return [String] the type of the state
+    attr_reader :type
+    # @return [String, nil] the next state name
+    attr_reader :next_state
+    # @return [Boolean] whether this is an end state
+    attr_reader :end_state
+
+    # @param name [String] the name of the state
+    # @param definition [Hash] the state definition
+    def initialize(name, definition)
+      @name = name
+      @type = definition["Type"]
+      @next_state = definition["Next"]
+      @end_state = definition.key?("End") && definition["End"]
+      @definition = definition
+    end
+
+    # Get the next state name (can be overridden by subclasses that need input)
+    # @param input [Hash, nil] the input data (optional, for choice states)
+    # @return [String, nil] the next state name
+    def next_state_name(input = nil)
+      return nil if end_state?
+      @next_state
+    end
+
+    # @return [Boolean] whether this state is an end state
+    def end_state?
+      @end_state
+    end
+
+    # Execute the state (to be implemented by subclasses)
+    # @param execution [Execution] the current execution
+    # @param input [Hash] the input data
+    # @return [Hash] the output data
+    # @raise [NotImplementedError] if not implemented by subclass
+    def execute(execution, input)
+      raise NotImplementedError, "Subclasses must implement execute method"
+    end
+  end
+end

data/lib/ruby_slm/state_machine.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require 'json'
+
+module StatesLanguageMachine
+  class StateMachine
+    # @return [Hash] the raw definition of the state machine
+    attr_reader :definition
+    # @return [Hash<String, States::Base>] mapping of state names to state objects
+    attr_reader :states
+    # @return [String] the name of the starting state
+    attr_reader :start_state
+    # @return [Integer, nil] the timeout in seconds for the entire state machine
+    attr_reader :timeout_seconds
+    # @return [String, nil] the comment describing the state machine
+    attr_reader :comment
+
+    # @param definition [String, Hash] the state machine definition
+    # @param format [Symbol] the format of the definition (:yaml, :json, :hash)
+    def initialize(definition, format: :yaml)
+      @definition = parse_definition(definition, format)
+      validate_definition!
+      build_states
+    end
+
+    # Start a new execution of this state machine
+    # @param input [Hash] the input data for the execution
+    # @param execution_name [String, nil] the name of the execution
+    # @param context [Hash] additional context for the execution
+    # @return [Execution] the execution object
+    def start_execution(input = {}, execution_name = nil, context = {})
+      Execution.new(self, input, execution_name, context)
+    end
+
+    # Get a state by name
+    # @param state_name [String] the name of the state to retrieve
+    # @return [States::Base] the state object
+    # @raise [StateNotFoundError] if the state is not found
+    def get_state(state_name)
+      @states[state_name] || raise(StateNotFoundError, "State '#{state_name}' not found")
+    end
+
+    # @return [Array<String>] the names of all states in the machine
+    def state_names
+      @states.keys
+    end
+
+    # @return [Hash] the state machine definition as a Hash
+    def to_h
+      @definition.dup
+    end
+
+    # @return [String] the state machine definition as JSON
+    def to_json
+      JSON.pretty_generate(@definition)
+    end
+
+    # @return [String] the state machine definition as YAML
+    def to_yaml
+      YAML.dump(@definition)
+    end
+
+    private
+
+    # @param definition [String, Hash] the definition to parse
+    # @param format [Symbol] the format of the definition
+    # @return [Hash] the parsed definition
+    def parse_definition(definition, format)
+      case format
+      when :yaml
+        YAML.safe_load(definition, permitted_classes: [Symbol], aliases: true)
+      when :json
+        JSON.parse(definition)
+      when :hash
+        definition
+      else
+        raise DefinitionError, "Unsupported format: #{format}"
+      end
+    end
+
+    # Validate the state machine definition
+    # @raise [DefinitionError] if the definition is invalid
+    def validate_definition!
+      raise DefinitionError, "Definition must be a Hash" unless @definition.is_a?(Hash)
+      raise DefinitionError, "Missing 'States' field" unless @definition["States"]
+      raise DefinitionError, "Missing 'StartAt' field" unless @definition["StartAt"]
+
+      @start_state = @definition["StartAt"]
+      @timeout_seconds = @definition["TimeoutSeconds"]
+      @comment = @definition["Comment"]
+
+      unless @definition["States"].key?(@start_state)
+        raise DefinitionError, "Start state '#{@start_state}' not found in States"
+      end
+    end
+
+    # Build state objects from the definition
+    def build_states
+      @states = {}
+
+      @definition["States"].each do |name, state_def|
+        @states[name] = create_state(name, state_def)
+      end
+    end
+
+    # Create a state object from its definition
+    # @param name [String] the name of the state
+    # @param state_def [Hash] the state definition
+    # @return [States::Base] the created state object
+    # @raise [DefinitionError] if the state type is unknown
+    # Create a state object from its definition
+    # @param name [String] the name of the state
+    # @param state_def [Hash] the state definition
+    # @return [States::Base] the created state object
+    # @raise [DefinitionError] if the state type is unknown
+    def create_state(name, state_def)
+      type = state_def["Type"]
+
+      case type
+      when "Task"
+        States::Task.new(name, state_def)
+      when "Choice"
+        States::Choice.new(name, state_def)
+      when "Wait"
+        States::Wait.new(name, state_def)
+      when "Parallel"
+        States::Parallel.new(name, state_def)
+      when "Pass"
+        States::Pass.new(name, state_def)
+      when "Succeed"
+        States::Succeed.new(name, state_def)
+      when "Fail"
+        States::Fail.new(name, state_def)
+      else
+        raise DefinitionError, "Unknown state type: #{type}"
+      end
+    end
+  end
+end

data/lib/ruby_slm/states/base.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module StatesLanguageMachine
+  module States
+    class Base < State
+      # @return [String, nil] the comment describing the state
+      attr_reader :comment
+      # @return [Hash] the raw state definition
+      attr_reader :definition
+
+      # @param name [String] the name of the state
+      # @param definition [Hash] the state definition
+      def initialize(name, definition)
+        super(name, definition)
+        @comment = definition["Comment"]
+        @definition = definition
+      end
+
+      # Validate the state definition
+      # @raise [DefinitionError] if the definition is invalid
+      def validate!
+        # Base validation - can be overridden by subclasses
+        if @end_state && @next_state
+          raise DefinitionError, "State '#{@name}' cannot have both End and Next"
+        end
+
+        unless @end_state || @next_state
+          raise DefinitionError, "State '#{@name}' must have either End or Next"
+        end
+      end
+
+      protected
+
+      # Process the execution result and update history
+      # @param execution [Execution] the current execution
+      # @param result [Hash] the result to process
+      def process_result(execution, result)
+        execution.update_output(result)
+        execution.add_history_entry(@name, result)
+      end
+
+
+      # Get a value from a nested hash using a dot-separated path
+      # @param data [Hash] the data to extract from
+      # @param path [String, nil] the dot-separated path
+      # @return [Object, nil] the value at the path, or nil if not found
+      def get_value_from_path(data, path)
+        return data unless path && data
+
+        # Handle nil or empty path
+        return data if path.nil? || path.empty?
+
+        # Remove leading '$.' if present (JSONPath format)
+        clean_path = path.start_with?('$.') ? path[2..] : path
+
+        # Handle root reference
+        return data if clean_path.empty?
+
+        # Split path and traverse
+        keys = clean_path.split('.')
+
+        current = data
+        keys.each do |key|
+          if current.is_a?(Hash) && current.key?(key)
+            current = current[key]
+          elsif current.is_a?(Array) && key =~ /^\d+$/
+            index = key.to_i
+            current = current[index] if index < current.length
+          else
+            # Return nil if any part of the path doesn't exist
+            return nil
+          end
+
+          # Break if we hit nil
+          break if current.nil?
+        end
+
+        current
+      end
+
+      # Set a value in a nested hash using a dot-separated path
+      # @param data [Hash] the data to modify
+      # @param path [String] the dot-separated path
+      # @param value [Object] the value to set
+      # @return [Hash] the modified data
+      def set_value_at_path(data, path, value)
+        return value unless path
+
+        keys = path.split('.')
+        final_key = keys.pop
+
+        target = keys.reduce(data) do |current, key|
+          current[key] ||= {}
+          current[key]
+        end
+
+        target[final_key] = value
+        data
+      end
+
+      # Deep merge two hashes
+      # @param hash1 [Hash] the first hash
+      # @param hash2 [Hash] the second hash
+      # @return [Hash] the merged hash
+      def deep_merge(hash1, hash2)
+        hash1.merge(hash2) do |key, old_val, new_val|
+          if old_val.is_a?(Hash) && new_val.is_a?(Hash)
+            deep_merge(old_val, new_val)
+          else
+            new_val
+          end
+        end
+      end
+
+      # Apply input path to filter input data
+      # @param input [Hash] the input data
+      # @param input_path [String, nil] the input path to apply
+      # @return [Hash] the filtered input data
+      def apply_input_path(input, input_path)
+        return input unless input_path
+        get_value_from_path(input, input_path) || {}
+      end
+
+      # Apply output path to filter output data
+      # @param output [Hash] the output data
+      # @param output_path [String, nil] the output path to apply
+      # @return [Hash] the filtered output data
+      def apply_output_path(output, output_path)
+        return output unless output_path
+        set_value_at_path({}, output_path, output)
+      end
+
+      # Apply result path to merge result with input
+      # @param input [Hash] the original input data
+      # @param result [Hash] the result data
+      # @param result_path [String, nil] the result path to apply
+      # @return [Hash] the merged data
+      def apply_result_path(input, result, result_path)
+        return result unless result_path
+
+        if result_path.nil?
+          input
+        else
+          set_value_at_path(input.dup, result_path, result)
+        end
+      end
+    end
+  end
+end

data/lib/ruby_slm/states/choice.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module StatesLanguageMachine
+  module States
+    class Choice < Base
+      attr_reader :choices, :default
+
+      def initialize(name, definition)
+        super
+        @choices = definition["Choices"] || []
+        @default = definition["Default"]
+        @evaluated_next_state = nil
+      end
+
+      def execute(execution, input)
+        execution.logger&.info("Executing choice state: #{@name}")
+
+        @evaluated_next_state = evaluate_choices(input, execution.logger)
+
+        execution.logger&.info("Selected next state: #{@evaluated_next_state}")
+        process_result(execution, input)
+        input
+      end
+
+      def next_state_name(input = nil)
+        return nil if end_state?
+        return @evaluated_next_state if @evaluated_next_state
+        input ? evaluate_choices(input) : @default
+      end
+
+      private
+
+      def evaluate_choices(input, logger = nil)
+        @choices.each do |choice|
+          puts choice
+          result = evaluate_choice(choice, input, logger)
+          puts result
+          if result
+            return choice["Next"]
+          end
+        end
+        @default
+      end
+
+      def evaluate_choice(choice, input, logger = nil)
+        if choice["And"]
+          return choice["And"].all? { |condition| evaluate_choice(condition, input, logger) }
+        end
+
+        if choice["Or"]
+          return choice["Or"].any? { |condition| evaluate_choice(condition, input, logger) }
+        end
+
+        if choice["Not"]
+          return !evaluate_choice(choice["Not"], input, logger)
+        end
+
+        condition_type = choice.keys.find { |k| !["Variable", "Next", "Comment"].include?(k) }
+        return false unless condition_type
+
+        variable_path = choice["Variable"]
+        expected_value = choice[condition_type]
+        actual_value = get_value_from_path(input, variable_path)
+
+        evaluate_simple_condition(condition_type, actual_value, expected_value, logger)
+      end
+
+      # Evaluate a simple condition
+      # @param condition_type [String] the type of condition
+      # @param actual_value [Object] the actual value from input
+      # @param expected_value [Object] the expected value from condition
+      # @param logger [Logger, nil] the logger for debug output
+      # @return [Boolean] whether the condition matches
+      def evaluate_simple_condition(condition_type, actual_value, expected_value, logger = nil)
+        puts condition_type
+        case condition_type
+        when "NumericEquals"
+          actual_num = to_number(actual_value)
+          expected_num = to_number(expected_value)
+          return false if actual_num.nil? || expected_num.nil?
+          actual_num == expected_num
+        when "NumericLessThan"
+          actual_num = to_number(actual_value)
+          expected_num = to_number(expected_value)
+          return false if actual_num.nil? || expected_num.nil?
+          puts "result of NumericLessThan", actual_num < expected_num
+          actual_num < expected_num
+        when "NumericGreaterThan"
+          actual_num = to_number(actual_value)
+          expected_num = to_number(expected_value)
+          return false if actual_num.nil? || expected_num.nil?
+          actual_num > expected_num
+        when "NumericLessThanEquals"
+          actual_num = to_number(actual_value)
+          expected_num = to_number(expected_value)
+          return false if actual_num.nil? || expected_num.nil?
+          actual_num <= expected_num
+        when "NumericGreaterThanEquals"
+          actual_num = to_number(actual_value)
+          expected_num = to_number(expected_value)
+          return false if actual_num.nil? || expected_num.nil?
+          actual_num >= expected_num
+        when "StringEquals"
+          actual_value.to_s == expected_value.to_s
+        when "BooleanEquals"
+          to_boolean(actual_value) == to_boolean(expected_value)
+        when "IsNull"
+          actual_value.nil?
+        when "IsPresent"
+          !actual_value.nil?
+        when "IsString"
+          actual_value.is_a?(String)
+        when "IsNumeric"
+          !!to_number(actual_value)
+        when "IsBoolean"
+          actual_value.is_a?(TrueClass) || actual_value.is_a?(FalseClass) ||
+            (actual_value.is_a?(String) && ["true", "false"].include?(actual_value.downcase))
+        else
+          false
+        end
+      end
+
+      def to_number(value)
+        return value if value.is_a?(Numeric)
+        return nil if value.nil?
+
+        if value.is_a?(String)
+          Float(value) rescue nil
+        else
+          Float(value) rescue nil
+        end
+      end
+
+      def to_boolean(value)
+        return value if [true, false].include?(value)
+        value.to_s.downcase == "true"
+      end
+
+      def validate!
+        # Skip base validation for choice states
+      end
+    end
+  end
+end