kumi 0.0.9 → 0.0.11

data/lib/kumi/core/function_registry/function_builder.rb

@@ -3,90 +3,179 @@
 module Kumi
   module Core
     module FunctionRegistry
-      # Utility class to reduce repetition in function definitions
       class FunctionBuilder
-        Entry = Struct.new(:fn, :arity, :param_types, :return_type, :description, :inverse, :reducer, keyword_init: true)
+        # Rich, defaulted function entry
+        class Entry
+          # NOTE: Keep ctor args minimal; everything else has sensible defaults.
+          attr_reader :fn, :arity, :param_types, :return_type, :description,
+                      :reducer, :structure_function, :param_modes, :param_info
 
-        def self.comparison(_name, description, operation)
+          # param_modes:  nil | ->(argc){[:elem,:scalar,...]} | {fixed: [...], variadic: :elem|:scalar}
+          # param_info:   nil | ->(argc){[specs]} | {fixed: [...], variadic: {…}}
+          #   where a spec is: { name:, type:, mode:, required:, default:, doc: }
+          def initialize(
+            fn:,
+            arity: nil,                 # Integer (>=0) or -1 / nil for variadic
+            param_types: nil,           # defaults to [:any] * arity (when fixed)
+            return_type: :any,
+            description: "",
+            reducer: false,
+            structure_function: false,
+            param_modes: nil,
+            param_info: nil
+          )
+            @fn                 = fn
+            @arity              = arity
+            @param_types        = param_types || default_param_types(arity)
+            @return_type        = return_type
+            @description        = description
+            @reducer            = !!reducer
+            @structure_function = !!structure_function
+            @param_modes        = normalize_param_modes(param_modes, arity)
+            @param_info         = normalize_param_info(param_info, arity, @param_types)
+          end
+
+          # Concrete modes for a call site
+          def param_modes_for(argc)
+            pm = @param_modes
+            return pm.call(argc) if pm.respond_to?(:call)
+
+            fixed = Array(pm[:fixed] || [])
+            return fixed.first(argc) if argc <= fixed.size
+
+            fixed + Array.new(argc - fixed.size, pm.fetch(:variadic, :elem))
+          end
+
+          # Concrete param specs for a call site
+          # → [{name:, type:, mode:, required:, default:, doc:}, ...]
+          def param_specs_for(argc)
+            base = if @param_info.respond_to?(:call)
+                     @param_info.call(argc)
+                   else
+                     fixed = Array(@param_info[:fixed] || [])
+                     if argc <= fixed.size
+                       fixed.first(argc)
+                     else
+                       fixed + Array.new(argc - fixed.size, @param_info.fetch(:variadic, {}))
+                     end
+                   end
+
+            modes = param_modes_for(argc)
+            types = expand_types_for(argc)
+
+            base.each_with_index.map do |spec, i|
+              {
+                name: spec[:name]     || auto_name(i),
+                type: spec[:type]     || types[i] || :any,
+                mode: spec[:mode]     || modes[i] || :elem,
+                required: spec.key?(:required) ? spec[:required] : true,
+                default: spec[:default],
+                doc: spec[:doc] || ""
+              }
+            end
+          end
+
+          private
+
+          def default_param_types(arity)
+            if arity.is_a?(Integer) && arity >= 0
+              Array.new(arity, :any)
+            else
+              [] # variadic → types resolved per call
+            end
+          end
+
+          def expand_types_for(argc)
+            if @param_types.nil? || @param_types.empty?
+              Array.new(argc, :any)
+            elsif @param_types.length >= argc
+              @param_types.first(argc)
+            else
+              @param_types + Array.new(argc - @param_types.length, @param_types.last || :any)
+            end
+          end
+
+          def normalize_param_modes(pm, arity)
+            return pm if pm
+
+            # Default: everything element-wise/broadcastable
+            ->(argc) { Array.new(argc, :elem) }
+          end
+
+          def normalize_param_info(info, arity, types)
+            return info if info
+
+            # Default: synthesize from types/modes at call time
+            ->(argc) { Array.new(argc) { {} } }
+          end
+
+          def auto_name(i) = :"arg#{i + 1}"
+        end
+
+        # ===== Helper constructors (unchanged usage; now benefit from defaults) =====
+
+        def self.comparison(_name, description, op)
           Entry.new(
-            fn: ->(a, b) { a.public_send(operation, b) },
-            arity: 2,
-            param_types: %i[float float],
-            return_type: :boolean,
-            description: description
+            fn: ->(a, b) { a.public_send(op, b) },
+            arity: 2, param_types: %i[float float],
+            return_type: :boolean, description: description
           )
         end
 
-        def self.equality(_name, description, operation)
+        def self.equality(_name, description, op)
           Entry.new(
-            fn: ->(a, b) { a.public_send(operation, b) },
-            arity: 2,
-            param_types: %i[any any],
-            return_type: :boolean,
-            description: description
+            fn: ->(a, b) { a.public_send(op, b) },
+            arity: 2, param_types: %i[any any],
+            return_type: :boolean, description: description
           )
         end
 
-        def self.math_binary(_name, description, operation, return_type: :float)
+        def self.math_binary(_name, description, op, return_type: :float)
           Entry.new(
-            fn: lambda { |a, b|
-              a.public_send(operation, b)
-            },
-            arity: 2,
-            param_types: %i[float float],
-            return_type: return_type,
-            description: description
+            fn: ->(a, b) { a.public_send(op, b) },
+            arity: 2, param_types: %i[float float],
+            return_type: return_type, description: description
           )
         end
 
-        def self.math_unary(_name, description, operation, return_type: :float)
+        def self.math_unary(_name, description, op, return_type: :float)
           Entry.new(
-            fn: proc(&operation),
-            arity: 1,
-            param_types: [:float],
-            return_type: return_type,
-            description: description
+            fn: proc(&op),
+            arity: 1, param_types: [:float],
+            return_type: return_type, description: description
           )
         end
 
-        def self.string_unary(_name, description, operation)
+        def self.string_unary(_name, description, op)
           Entry.new(
-            fn: ->(str) { str.to_s.public_send(operation) },
-            arity: 1,
-            param_types: [:string],
-            return_type: :string,
-            description: description
+            fn: ->(s) { s.to_s.public_send(op) },
+            arity: 1, param_types: [:string],
+            return_type: :string, description: description
           )
         end
 
-        def self.string_binary(_name, description, operation, return_type: :string)
+        def self.string_binary(_name, description, op, return_type: :string)
           Entry.new(
-            fn: ->(str, arg) { str.to_s.public_send(operation, arg.to_s) },
-            arity: 2,
-            param_types: %i[string string],
-            return_type: return_type,
-            description: description
+            fn: ->(s, x) { s.to_s.public_send(op, x.to_s) },
+            arity: 2, param_types: %i[string string],
+            return_type: return_type, description: description
           )
         end
 
-        def self.logical_variadic(_name, description, operation)
+        def self.logical_variadic(_name, description, op)
           Entry.new(
-            fn: ->(conditions) { conditions.public_send(operation) },
-            arity: -1,
-            param_types: [:boolean],
-            return_type: :boolean,
-            description: description
+            fn: ->(*conds) { conds.flatten.public_send(op) },
+            arity: -1, param_types: [:boolean],
+            return_type: :boolean, description: description
           )
         end
 
-        def self.collection_unary(_name, description, operation, return_type: :boolean, reducer: false)
+        def self.collection_unary(_name, description, op, return_type: :boolean, reducer: false, structure_function: false)
           Entry.new(
-            fn: proc(&operation),
-            arity: 1,
-            param_types: [Kumi::Core::Types.array(:any)],
-            return_type: return_type,
-            description: description,
-            reducer: reducer
+            fn: proc(&op),
+            arity: 1, param_types: [Kumi::Core::Types.array(:any)],
+            return_type: return_type, description: description,
+            reducer: reducer, structure_function: structure_function
           )
         end
       end

data/lib/kumi/core/function_registry/logical_functions.rb

@@ -5,6 +5,146 @@ module Kumi
     module FunctionRegistry
       # Logical operations and boolean functions
       module LogicalFunctions
+        def self.element_wise_and(a, b)
+          if ENV["DEBUG_CASCADE"]
+            puts "DEBUG element_wise_and called with:"
+            puts "  a: #{a.inspect} (depth: #{array_depth(a)})"
+            puts "  b: #{b.inspect} (depth: #{array_depth(b)})"
+          end
+
+          case [a.class, b.class]
+          when [Array, Array]
+            # Both are arrays - handle hierarchical broadcasting
+            if hierarchical_broadcasting_needed?(a, b)
+              puts "  -> Using hierarchical broadcasting" if ENV["DEBUG_CASCADE"]
+              result = perform_hierarchical_and(a, b)
+              puts "  -> Hierarchical result: #{result.inspect}" if ENV["DEBUG_CASCADE"]
+            else
+              # Same structure - use zip for element-wise operations
+              puts "  -> Using same-structure zip" if ENV["DEBUG_CASCADE"]
+              result = a.zip(b).map { |elem_a, elem_b| element_wise_and(elem_a, elem_b) }
+              puts "  -> Zip result: #{result.inspect}" if ENV["DEBUG_CASCADE"]
+            end
+            result
+          when [Array, Object], [Object, Array]
+            # One is array, one is scalar - broadcast scalar
+            puts "  -> Broadcasting scalar to array" if ENV["DEBUG_CASCADE"]
+            result = if a.is_a?(Array)
+                       a.map { |elem| element_wise_and(elem, b) }
+                     else
+                       b.map { |elem| element_wise_and(a, elem) }
+                     end
+            puts "  -> Broadcast result: #{result.inspect}" if ENV["DEBUG_CASCADE"]
+            result
+          else
+            # Both are scalars - simple AND
+            puts "  -> Simple scalar AND: #{a} && #{b} = #{a && b}" if ENV["DEBUG_CASCADE"]
+            a && b
+          end
+        end
+
+        def self.hierarchical_broadcasting_needed?(a, b)
+          # Check if arrays have different nesting depths (hierarchical broadcasting)
+          depth_a = array_depth(a)
+          depth_b = array_depth(b)
+          depth_a != depth_b
+        end
+
+        def self.array_depth(arr)
+          return 0 unless arr.is_a?(Array)
+          return 1 if arr.empty? || !arr.first.is_a?(Array)
+
+          1 + array_depth(arr.first)
+        end
+
+        def self.perform_hierarchical_and(a, b)
+          # Determine which is the higher dimension and which is lower
+          depth_a = array_depth(a)
+          depth_b = array_depth(b)
+
+          puts "    perform_hierarchical_and: depth_a=#{depth_a}, depth_b=#{depth_b}" if ENV["DEBUG_CASCADE"]
+
+          if depth_a > depth_b
+            # a is deeper (child level), b is shallower (parent level)
+            # Broadcast b values to match a's structure - PRESERVE a's structure
+            puts "    -> Broadcasting b (parent) to match a (child) structure" if ENV["DEBUG_CASCADE"]
+            broadcast_parent_to_child_structure(a, b)
+          else
+            # b is deeper (child level), a is shallower (parent level)
+            # Broadcast a values to match b's structure - PRESERVE b's structure
+            puts "    -> Broadcasting a (parent) to match b (child) structure" if ENV["DEBUG_CASCADE"]
+            broadcast_parent_to_child_structure(b, a)
+          end
+        end
+
+        def self.broadcast_parent_to_child_structure(child_array, parent_array)
+          # Broadcast parent array values to match child array structure, preserving child structure
+          if ENV["DEBUG_CASCADE"]
+            puts "      broadcast_parent_to_child_structure:"
+            puts "        child_array: #{child_array.inspect}"
+            puts "        parent_array: #{parent_array.inspect}"
+            puts "        child depth: #{array_depth(child_array)}, parent depth: #{array_depth(parent_array)}"
+          end
+
+          # Use child array structure as template and broadcast parent values
+          map_with_parent_broadcasting(child_array, parent_array, [])
+        end
+
+        def self.map_with_parent_broadcasting(child_structure, parent_structure, indices)
+          if child_structure.is_a?(Array)
+            child_structure.map.with_index do |child_elem, index|
+              new_indices = indices + [index]
+
+              # Navigate parent structure with fewer indices (broadcasting)
+              parent_depth = array_depth(parent_structure)
+              parent_indices = new_indices[0, parent_depth]
+              parent_value = navigate_indices(parent_structure, parent_indices)
+
+              if child_elem.is_a?(Array)
+                # Recurse deeper into child structure
+                map_with_parent_broadcasting(child_elem, parent_structure, new_indices)
+              else
+                # Leaf level - apply AND operation
+                result = child_elem && parent_value
+                if ENV["DEBUG_CASCADE"]
+                  puts "          Leaf: child=#{child_elem}, parent=#{parent_value} (indices #{new_indices.inspect}) -> #{result}"
+                end
+                result
+              end
+            end
+          else
+            # Non-array child - just AND with parent
+            child_structure && parent_structure
+          end
+        end
+
+        def self.navigate_indices(structure, indices)
+          return structure if indices.empty?
+          return structure unless structure.is_a?(Array)
+          return nil if indices.first >= structure.length
+
+          navigate_indices(structure[indices.first], indices[1..])
+        end
+
+        def self.broadcast_to_match_structure(child_array, parent_array)
+          # Legacy method - keeping for backward compatibility
+          if ENV["DEBUG_CASCADE"]
+            puts "      broadcast_to_match_structure (LEGACY):"
+            puts "        child_array: #{child_array.inspect}"
+            puts "        parent_array: #{parent_array.inspect}"
+            puts "        child_array.length: #{child_array.length}"
+            puts "        parent_array.length: #{parent_array.length}"
+          end
+
+          result = child_array.zip(parent_array).map do |child_elem, parent_elem|
+            puts "        Combining child_elem: #{child_elem.inspect} with parent_elem: #{parent_elem.inspect}" if ENV["DEBUG_CASCADE"]
+            element_wise_and(child_elem, parent_elem)
+          end
+
+          puts "        broadcast result: #{result.inspect}" if ENV["DEBUG_CASCADE"]
+          result
+        end
+
         def self.definitions
           {
             # Basic logical operations
@@ -33,9 +173,39 @@ module Kumi
             ),
 
             # Collection logical operations
-            all?: FunctionBuilder.collection_unary(:all?, "Check if all elements in collection are truthy", :all?),
-            any?: FunctionBuilder.collection_unary(:any?, "Check if any element in collection is truthy", :any?),
-            none?: FunctionBuilder.collection_unary(:none?, "Check if no elements in collection are truthy", :none?)
+            all?: FunctionBuilder.collection_unary(:all?, "Check if all elements in collection are truthy", :all?, reducer: true),
+            any?: FunctionBuilder.collection_unary(:any?, "Check if any element in collection is truthy", :any?, reducer: true),
+            none?: FunctionBuilder.collection_unary(:none?, "Check if no elements in collection are truthy", :none?, reducer: true),
+
+            # Element-wise AND for cascades - works on arrays with same structure
+            cascade_and: FunctionBuilder::Entry.new(
+              fn: lambda do |*conditions|
+                if ENV["DEBUG_CASCADE"]
+                  puts "DEBUG cascade_and called with #{conditions.length} conditions:"
+                  conditions.each_with_index do |cond, i|
+                    puts "  condition[#{i}]: #{cond.inspect}"
+                  end
+                end
+
+                return false if conditions.empty?
+
+                # Always process uniformly, even for single conditions
+                # This ensures DeclarationReferences are evaluated properly
+                result = conditions.first
+                conditions[1..].each_with_index do |condition, i|
+                  puts "  Combining result with condition[#{i + 1}]" if ENV["DEBUG_CASCADE"]
+                  result = LogicalFunctions.element_wise_and(result, condition)
+                  puts "  Result after combining: #{result.inspect}" if ENV["DEBUG_CASCADE"]
+                end
+
+                puts "  Final cascade_and result: #{result.inspect}" if ENV["DEBUG_CASCADE"]
+                result
+              end,
+              arity: -1,
+              param_types: [:boolean],
+              return_type: :boolean,
+              description: "Element-wise AND for arrays with same nested structure"
+            )
           }
         end
       end

data/lib/kumi/core/function_registry/stat_functions.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Core
+    module FunctionRegistry
+      module StatFunctions
+        def self.definitions
+          {
+            # Statistical Functions
+            avg: FunctionBuilder::Entry.new(
+              fn: ->(array) { array.empty? ? nil : array.sum.to_f / array.size },
+              arity: 1,
+              param_types: [Kumi::Core::Types.array(:float)],
+              return_type: :float,
+              description: "Calculate arithmetic mean (average) of numeric collection",
+              reducer: true
+            ),
+
+            mean: FunctionBuilder::Entry.new(
+              fn: ->(array) { array.empty? ? nil : array.sum.to_f / array.size },
+              arity: 1,
+              param_types: [Kumi::Core::Types.array(:float)],
+              return_type: :float,
+              description: "Calculate arithmetic mean (average) of numeric collection (alias for avg)",
+              reducer: true
+            ),
+
+            median: FunctionBuilder::Entry.new(
+              fn: lambda do |array|
+                sorted = array.sort
+                len = sorted.length
+                if len.odd?
+                  sorted[len / 2]
+                else
+                  (sorted[(len / 2) - 1] + sorted[len / 2]) / 2.0
+                end
+              end,
+              arity: 1,
+              param_types: [Kumi::Core::Types.array(:float)],
+              return_type: :float,
+              description: "Calculate median (middle value) of numeric collection",
+              reducer: true
+            ),
+
+            variance: FunctionBuilder::Entry.new(
+              fn: lambda do |array|
+                mean = array.sum.to_f / array.size
+                sum_of_squares = array.sum { |x| (x - mean)**2 }
+                sum_of_squares / array.size
+              end,
+              arity: 1,
+              param_types: [Kumi::Core::Types.array(:float)],
+              return_type: :float,
+              description: "Calculate population variance of numeric collection",
+              reducer: true
+            ),
+
+            stdev: FunctionBuilder::Entry.new(
+              fn: lambda do |array|
+                mean = array.sum.to_f / array.size
+                sum_of_squares = array.sum { |x| (x - mean)**2 }
+                variance = sum_of_squares / array.size
+                Math.sqrt(variance)
+              end,
+              arity: 1,
+              param_types: [Kumi::Core::Types.array(:float)],
+              return_type: :float,
+              description: "Calculate population standard deviation of numeric collection",
+              reducer: true
+            ),
+
+            sample_variance: FunctionBuilder::Entry.new(
+              fn: lambda do |array|
+                return 0.0 if array.size <= 1
+
+                mean = array.sum.to_f / array.size
+                sum_of_squares = array.sum { |x| (x - mean)**2 }
+                sum_of_squares / (array.size - 1)
+              end,
+              arity: 1,
+              param_types: [Kumi::Core::Types.array(:float)],
+              return_type: :float,
+              description: "Calculate sample variance of numeric collection",
+              reducer: true
+            ),
+
+            sample_stdev: FunctionBuilder::Entry.new(
+              fn: lambda do |array|
+                return 0.0 if array.size <= 1
+
+                mean = array.sum.to_f / array.size
+                sum_of_squares = array.sum { |x| (x - mean)**2 }
+                variance = sum_of_squares / (array.size - 1)
+                Math.sqrt(variance)
+              end,
+              arity: 1,
+              param_types: [Kumi::Core::Types.array(:float)],
+              return_type: :float,
+              description: "Calculate sample standard deviation of numeric collection",
+              reducer: true
+            ),
+
+            # Convenience functions for flattened statistics
+            flat_size: FunctionBuilder::Entry.new(
+              fn: ->(nested_array) { nested_array.flatten.size },
+              arity: 1,
+              param_types: [Kumi::Core::Types.array(:any)],
+              return_type: :integer,
+              description: "Count total elements across all nested levels",
+              reducer: true
+            ),
+
+            flat_sum: FunctionBuilder::Entry.new(
+              fn: ->(nested_array) { nested_array.flatten.sum },
+              arity: 1,
+              param_types: [Kumi::Core::Types.array(:float)],
+              return_type: :float,
+              description: "Sum all numeric elements across all nested levels",
+              reducer: true
+            ),
+
+            flat_avg: FunctionBuilder::Entry.new(
+              fn: lambda do |nested_array|
+                flattened = nested_array.flatten
+                flattened.sum.to_f / flattened.size
+              end,
+              arity: 1,
+              param_types: [Kumi::Core::Types.array(:float)],
+              return_type: :float,
+              description: "Calculate average across all nested levels",
+              reducer: true
+            ),
+
+            flat_max: FunctionBuilder::Entry.new(
+              fn: ->(nested_array) { nested_array.flatten.max },
+              arity: 1,
+              param_types: [Kumi::Core::Types.array(:float)],
+              return_type: :float,
+              description: "Find maximum value across all nested levels",
+              reducer: true
+            ),
+
+            flat_min: FunctionBuilder::Entry.new(
+              fn: ->(nested_array) { nested_array.flatten.min },
+              arity: 1,
+              param_types: [Kumi::Core::Types.array(:float)],
+              return_type: :float,
+              description: "Find minimum value across all nested levels",
+              reducer: true
+            )
+          }
+        end
+      end
+    end
+  end
+end