stellwerk-ruby 0.1.0

data/lib/stellwerk/flow.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Stellwerk
+  # Convenience wrapper for loading and executing compiled flows
+  class Flow
+    attr_reader :compiled_json, :path
+
+    # Load a flow from a JSON file
+    #
+    # @param path [String] Path to the compiled JSON file
+    # @return [Stellwerk::Flow]
+    # @raise [InvalidFlowError] if the file doesn't exist or contains invalid JSON
+    def self.load(path)
+      unless File.exist?(path)
+        raise InvalidFlowError, "Flow file not found: #{path}"
+      end
+
+      content = File.read(path)
+      json = JSON.parse(content)
+
+      new(json, path: path)
+    rescue JSON::ParserError => e
+      raise InvalidFlowError, "Invalid JSON in flow file: #{e.message}"
+    end
+
+    # Create a flow from a parsed JSON hash
+    #
+    # @param compiled_json [Hash] The compiled flow JSON
+    # @param path [String, nil] Optional path for debugging
+    def initialize(compiled_json, path: nil)
+      @compiled_json = compiled_json
+      @path = path
+      validate!
+    end
+
+    # Execute the flow with the given parameters
+    #
+    # @param params [Hash] Input parameters for the flow
+    # @param sub_flows [Hash] Additional sub-flows for map nodes
+    # @param metadata [Hash] Additional metadata to merge into context
+    # @return [Stellwerk::Result]
+    def execute(params = {}, sub_flows: {}, metadata: {})
+      Evaluator.call(
+        compiled_json: @compiled_json,
+        params: params,
+        sub_flows: sub_flows,
+        metadata: metadata
+      )
+    end
+
+    # Get the flow version from compiled JSON
+    def version
+      @compiled_json["version"] || @compiled_json[:version]
+    end
+
+    # Get compilation timestamp
+    def compiled_at
+      @compiled_json["compiled_at"] || @compiled_json[:compiled_at]
+    end
+
+    # Get entry node IDs
+    def entry_node_ids
+      @compiled_json["entry_node_ids"] || @compiled_json[:entry_node_ids] || []
+    end
+
+    # Get all node IDs
+    def node_ids
+      nodes = @compiled_json["nodes"] || @compiled_json[:nodes] || {}
+      nodes.keys
+    end
+
+    private
+
+    def validate!
+      nodes = @compiled_json["nodes"] || @compiled_json[:nodes]
+      unless nodes.is_a?(Hash)
+        raise InvalidFlowError, "Compiled flow must have a 'nodes' hash"
+      end
+
+      entry_ids = @compiled_json["entry_node_ids"] || @compiled_json[:entry_node_ids]
+      if nodes.any? && (entry_ids.nil? || entry_ids.empty?)
+        Stellwerk.logger.warn("Flow has nodes but no entry_node_ids defined")
+      end
+    end
+  end
+end

data/lib/stellwerk/functions.rb

@@ -0,0 +1,318 @@
+# frozen_string_literal: true
+
+require "dentaku"
+
+# Collection & aggregation helper functions for Dentaku.
+# We override common aggregators (SUM, COUNT, MIN, MAX) to be dual-mode:
+#  - Classic Dentaku usage: SUM(a, b, c)
+#  - Array mode: SUM(array) or SUM(array_of_numbers) or SUM(array_of_mixed)
+# Additional functions: FIRST, LAST, TAKE, PROJECT (internal helper)
+# Projection pattern: identifier[*].field is preprocessed into PROJECT(identifier, "field")
+# Mixed-type coercion:
+#  - Numeric values kept
+#  - Numeric-looking strings converted to Float
+#  - nil ignored
+#  - Other types ignored for numeric aggregations
+#  - If no numeric values remain -> SUM = 0, MIN/MAX = nil, COUNT counts *all non-nil projected elements* (not just numeric)
+# TAKE(array, n) -> first n elements (n coerced to integer, negative treated as 0)
+# FIRST(array) / LAST(array) -> element or nil
+
+module Stellwerk
+  module Functions
+    module_function
+
+    def ensure_array(arg)
+      return [] if arg.nil?
+      return arg if arg.is_a?(Array)
+      [arg]
+    end
+
+    def coerce_numeric_list(list)
+      list.filter_map do |v|
+        case v
+        when Numeric then v.to_f
+        when String
+          v_strip = v.strip
+          if v_strip.match?(/^[-+]?\d+(?:\.\d+)?$/)
+            v_strip.to_f
+          end
+        else
+          nil
+        end
+      end
+    end
+
+    # Internal projection helper: given an array of hashes (or objects responding to [] / .public_send)
+    # and a field name, extract that field, allowing nils.
+    # Named PROJECT (instead of __project) because Dentaku will constantize function names.
+    def PROJECT(collection, field_name)
+      arr = ensure_array(collection)
+      arr.map do |item|
+        if item.is_a?(Hash)
+          item[field_name.to_sym] || item[field_name.to_s]
+        elsif item.respond_to?(:[]) && !item.is_a?(String)
+          begin
+            item[field_name]
+          rescue StandardError
+            nil
+          end
+        elsif item.respond_to?(field_name)
+          begin
+            item.public_send(field_name)
+          rescue StandardError
+            nil
+          end
+        else
+          nil
+        end
+      end
+    end
+
+    # DEEP_PROJECT(root, path_string, field_name)
+    # Traverse a dotted path to reach an array, then extract field_name from each element.
+    # Example: DEEP_PROJECT(order, "items", "price") where order[:items] is an array of hashes.
+    def DEEP_PROJECT(root, path_string, field_name)
+      return [] if root.nil?
+      current = root
+      path_segments = path_string.to_s.split(".")
+      path_segments.each do |seg|
+        break if current.nil?
+        if current.is_a?(Hash)
+          current = current[seg.to_sym] || current[seg.to_s]
+        elsif current.respond_to?(seg)
+          begin
+            current = current.public_send(seg)
+          rescue StandardError
+            current = nil
+          end
+        else
+          current = nil
+        end
+      end
+      arr = ensure_array(current)
+      arr.map do |item|
+        if item.is_a?(Hash)
+          item[field_name.to_sym] || item[field_name.to_s]
+        elsif item.respond_to?(:[]) && !item.is_a?(String)
+          begin
+            item[field_name]
+          rescue StandardError
+            nil
+          end
+        elsif item.respond_to?(field_name)
+          begin
+            item.public_send(field_name)
+          rescue StandardError
+            nil
+          end
+        else
+          nil
+        end
+      end
+    end
+
+    # SUM dual mode
+    def SUM(*args)
+      values = if args.length == 1 && args.first.is_a?(Array)
+        coerce_numeric_list(args.first)
+      else
+        coerce_numeric_list(args)
+      end
+      values.sum
+    end
+
+    # COUNT dual mode: counts non-nil entries. If single array arg, count its non-nil members.
+    def COUNT(*args)
+      if args.length == 1 && args.first.is_a?(Array)
+        args.first.compact.length
+      else
+        args.compact.length
+      end
+    end
+
+    # MIN dual mode: returns nil if no numeric values
+    def MIN(*args)
+      values = if args.length == 1 && args.first.is_a?(Array)
+        coerce_numeric_list(args.first)
+      else
+        coerce_numeric_list(args)
+      end
+      values.min
+    end
+
+    # MAX dual mode: returns nil if no numeric values
+    def MAX(*args)
+      values = if args.length == 1 && args.first.is_a?(Array)
+        coerce_numeric_list(args.first)
+      else
+        coerce_numeric_list(args)
+      end
+      values.max
+    end
+
+    def FIRST(arg)
+      arr = ensure_array(arg)
+      arr.first
+    end
+
+    def LAST(arg)
+      arr = ensure_array(arg)
+      arr.last
+    end
+
+    def TAKE(arg, n)
+      arr = ensure_array(arg)
+      limit = begin
+        Integer(n)
+      rescue StandardError
+        0
+      end
+      return [] if limit <= 0
+      arr.first(limit)
+    end
+
+    # -----------------------------
+    # Phase 2 Functions
+    # -----------------------------
+    # MAP(collection, expr_string, safe: false)
+    #  - Applies a Dentaku expression to each element with variable 'item' bound to element
+    # FILTER(collection, predicate_expr)
+    #  - Keeps elements where predicate_expr evaluates truthy
+    # DISTINCT(collection)
+    #  - Removes duplicates via Ruby equality
+    # AVERAGE/AVG dual-mode like SUM but returns nil if no numeric values
+    # SUMIF(collection, predicate_expr, projection_expr=nil)
+    #  - If projection_expr provided, sum of projection for items where predicate matches
+    #  - Else sum of numeric-looking items themselves
+    # COUNTIF(collection, predicate_expr)
+    #  - Count of elements where predicate is truthy
+    # TRACE(value, label=nil)
+    #  - Returns value unchanged; placeholder for future instrumentation hook
+
+    def MAP(collection, expr, calculator: Dentaku::Calculator.new)
+      arr = ensure_array(collection)
+      return [] if expr.nil? || expr.strip.empty?
+      arr.map do |item|
+        begin
+          # Provide 'item' binding; if item is a Hash, flatten simple keys
+          ctx = { "item" => item }
+          if item.is_a?(Hash)
+            item.each { |k, v| ctx[k.to_s] = v }
+          end
+          calculator.evaluate!(expr, ctx)
+        rescue StandardError
+          nil
+        end
+      end
+    end
+
+    def FILTER(collection, predicate_expr, calculator: Dentaku::Calculator.new)
+      arr = ensure_array(collection)
+      return arr if predicate_expr.nil? || predicate_expr.strip.empty?
+      arr.select do |item|
+        begin
+          ctx = { "item" => item }
+          if item.is_a?(Hash)
+            item.each { |k, v| ctx[k.to_s] = v }
+          end
+          !!calculator.evaluate!(predicate_expr, ctx)
+        rescue StandardError
+          false
+        end
+      end
+    end
+
+    def DISTINCT(collection)
+      ensure_array(collection).uniq
+    end
+
+    def AVERAGE(*args)
+      values = if args.length == 1 && args.first.is_a?(Array)
+        coerce_numeric_list(args.first)
+      else
+        coerce_numeric_list(args)
+      end
+      return nil if values.empty?
+      values.sum / values.length.to_f
+    end
+    alias AVG AVERAGE
+
+    def SUMIF(collection, predicate_expr, projection_expr = nil, calculator: Dentaku::Calculator.new)
+      arr = ensure_array(collection)
+      return 0 if predicate_expr.nil? || predicate_expr.strip.empty?
+      total = 0.0
+      arr.each do |item|
+        begin
+          ctx = { "item" => item }
+          if item.is_a?(Hash)
+            item.each { |k, v| ctx[k.to_s] = v }
+          end
+          next unless calculator.evaluate!(predicate_expr, ctx)
+          value = if projection_expr && !projection_expr.strip.empty?
+            calculator.evaluate!(projection_expr, ctx) rescue nil
+          else
+            item
+          end
+          case value
+          when Numeric
+            total += value.to_f
+          when String
+            v = value.strip
+            total += v.to_f if v.match?(/^[-+]?\d+(?:\.\d+)?$/)
+          end
+        rescue StandardError
+          next
+        end
+      end
+      total
+    end
+
+    def COUNTIF(collection, predicate_expr, calculator: Dentaku::Calculator.new)
+      arr = ensure_array(collection)
+      return 0 if predicate_expr.nil? || predicate_expr.strip.empty?
+      count = 0
+      arr.each do |item|
+        begin
+          ctx = { "item" => item }
+          if item.is_a?(Hash)
+            item.each { |k, v| ctx[k.to_s] = v }
+          end
+          count += 1 if calculator.evaluate!(predicate_expr, ctx)
+        rescue StandardError
+          # ignore
+        end
+      end
+      count
+    end
+
+    def REDUCE(collection, initial, expr, calculator: Dentaku::Calculator.new)
+      arr = ensure_array(collection)
+      return initial if arr.empty?
+
+      accumulator = initial
+      arr.each do |item|
+        begin
+          ctx = { "item" => item, "accumulator" => accumulator, "acc" => accumulator }
+          if item.is_a?(Hash)
+            item.each { |k, v| ctx[k.to_s] = v }
+          end
+          accumulator = calculator.evaluate!(expr, ctx)
+        rescue StandardError
+          nil
+        end
+      end
+      accumulator
+    end
+
+    def TRACE(value, _label = nil)
+      # Future: push to instrumentation buffer
+      value
+    end
+
+    # ARRAY function - creates an array from arguments
+    # Allows: values = ARRAY(1, 2, 3) which can then be used with SUM(values)
+    def ARRAY(*args)
+      args
+    end
+  end
+end

data/lib/stellwerk/result.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Stellwerk
+  # Represents the result of a flow execution
+  class Result
+    attr_reader :outputs, :errors, :applied_nodes, :context
+
+    def initialize(outputs:, errors:, applied_nodes:, context:)
+      @outputs = outputs || {}
+      @errors = errors || []
+      @applied_nodes = applied_nodes || []
+      @context = context || {}
+    end
+
+    # Returns true if the flow executed without errors
+    def success?
+      errors.empty?
+    end
+
+    # Returns true if there were any errors during execution
+    def failure?
+      !success?
+    end
+
+    # Convert to hash representation
+    def to_h
+      {
+        outputs: outputs,
+        errors: errors,
+        applied_nodes: applied_nodes,
+        context: context
+      }
+    end
+  end
+end

data/lib/stellwerk/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Stellwerk
+  VERSION = "0.1.0"
+end

data/lib/stellwerk.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "logger"
+
+require_relative "stellwerk/version"
+require_relative "stellwerk/errors"
+require_relative "stellwerk/result"
+require_relative "stellwerk/functions"
+require_relative "stellwerk/evaluator"
+require_relative "stellwerk/flow"
+
+# Stellwerk - A standalone Ruby gem for evaluating pre-compiled flow JSON
+#
+# This gem provides a Rails-free implementation for executing flows that have
+# been compiled by the Stellwerk platform. It works with the compiled JSON
+# format that includes all node definitions, adjacency lists, and embedded
+# sub-flows.
+#
+# @example Simple usage
+#   flow = Stellwerk::Flow.load('pricing.compiled.json')
+#   result = flow.execute(quantity: 10, price: 25.00)
+#
+#   if result.success?
+#     puts result.outputs[:total]
+#   else
+#     puts result.errors
+#   end
+#
+# @example Direct evaluator usage
+#   json = JSON.parse(File.read('flow.json'))
+#   result = Stellwerk::Evaluator.call(compiled_json: json, params: { x: 10 })
+#
+# @example Configuration
+#   Stellwerk.configure do |config|
+#     config.logger = Logger.new(STDOUT)
+#   end
+#
+module Stellwerk
+  class << self
+    # Configuration options
+    attr_writer :logger
+
+    # Returns the configured logger (defaults to a null logger)
+    def logger
+      @logger ||= Logger.new(File::NULL)
+    end
+
+    # Configure Stellwerk
+    #
+    # @yield [self] Yields self for configuration
+    def configure
+      yield self
+    end
+
+    # Reset configuration to defaults
+    def reset!
+      @logger = nil
+    end
+  end
+end

metadata

@@ -0,0 +1,115 @@
+--- !ruby/object:Gem::Specification
+name: stellwerk-ruby
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Roadwerk
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-01-31 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: dentaku
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+description: |
+  Stellwerk is a standalone Ruby gem for evaluating pre-compiled flow JSON
+  without any Rails or ActiveRecord dependencies. It provides a fast, portable
+  way to execute decision logic and calculations defined in the Stellwerk platform.
+email:
+- team@roadwerk.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/stellwerk.rb
+- lib/stellwerk/errors.rb
+- lib/stellwerk/evaluator.rb
+- lib/stellwerk/flow.rb
+- lib/stellwerk/functions.rb
+- lib/stellwerk/result.rb
+- lib/stellwerk/version.rb
+homepage: https://github.com/roadwerk/stellwerk-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/roadwerk/stellwerk-ruby
+  source_code_uri: https://github.com/roadwerk/stellwerk-ruby
+  changelog_uri: https://github.com/roadwerk/stellwerk-ruby/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: Evaluate pre-compiled Stellwerk flows in pure Ruby
+test_files: []