kumi 0.0.9 → 0.0.10

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.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.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

data/lib/kumi/core/function_registry.rb

@@ -2,8 +2,8 @@
 
 module Kumi
   module Core
-    # Registry for functions that can be used in Kumi schemas
-    # This is the public interface for registering custom functions
+    # Internal function registry implementation
+    # Use Kumi::Registry for the public interface to register custom functions
     module FunctionRegistry
       # Re-export the Entry struct from FunctionBuilder for compatibility
       Entry = FunctionBuilder::Entry
@@ -13,20 +13,33 @@ module Kumi
 
       # Build the complete function registry by combining all categories
       CORE_FUNCTIONS = {}.tap do |registry|
-        registry.merge!(ComparisonFunctions.definitions)
-        registry.merge!(MathFunctions.definitions)
-        registry.merge!(StringFunctions.definitions)
-        registry.merge!(LogicalFunctions.definitions)
-        registry.merge!(CollectionFunctions.definitions)
-        registry.merge!(ConditionalFunctions.definitions)
-        registry.merge!(TypeFunctions.definitions)
+        function_modules = [
+          ComparisonFunctions.definitions,
+          MathFunctions.definitions,
+          StringFunctions.definitions,
+          LogicalFunctions.definitions,
+          CollectionFunctions.definitions,
+          ConditionalFunctions.definitions,
+          TypeFunctions.definitions,
+          StatFunctions.definitions
+        ]
+
+        function_modules.each do |module_definitions|
+          module_definitions.each do |name, definition|
+            if registry.key?(name)
+              raise ArgumentError, "Function #{name.inspect} is already registered. Found duplicate in function registry."
+            end
+
+            registry[name] = definition
+          end
+        end
       end.freeze
 
       @functions = CORE_FUNCTIONS.dup
       @frozen = false
 
       # class << self
-      # Public interface for registering custom functions
+      # Internal interface for registering custom functions
       def register(name, &block)
         raise ArgumentError, "Function #{name.inspect} already registered" if @functions.key?(name)
 
@@ -97,6 +110,11 @@ module Kumi
         entry.reducer || false
       end
 
+      def structure_function?(name)
+        entry = @functions.fetch(name) { return false }
+        entry.structure_function || false
+      end
+
       # Alias for compatibility
       def all
         @functions.keys
@@ -130,6 +148,10 @@ module Kumi
       def type_operations
         TypeFunctions.definitions.keys
       end
+
+      def stat_operations
+        StatFunctions.definitions.keys
+      end
     end
   end
 end

data/lib/kumi/core/nested_structure_utils.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Core
+    # Shared utilities for working with nested array structures
+    module NestedStructureUtils
+      def calculate_array_depth(arr)
+        return 0 unless arr.is_a?(Array)
+        return 1 if arr.empty? || !arr.first.is_a?(Array)
+
+        1 + calculate_array_depth(arr.first)
+      end
+
+      def map_nested_structure(structure, indices = [], &block)
+        if structure.is_a?(Array) && structure.first.is_a?(Array)
+          # Still nested - recurse deeper
+          structure.map.with_index do |sub_structure, i|
+            map_nested_structure(sub_structure, indices + [i], &block)
+          end
+        elsif structure.is_a?(Array)
+          # Leaf array level - apply function to elements
+          structure.map.with_index do |_element, i|
+            yield(*(indices + [i]))
+          end
+        else
+          # Single element - apply function
+          yield(*indices)
+        end
+      end
+
+      def navigate_nested_indices(structure, indices)
+        indices.reduce(structure) do |current, index|
+          if current.is_a?(Array)
+            current[index]
+          else
+            # If we hit a non-array during navigation, it means we're dealing with
+            # mixed nesting levels - return the current value
+            current
+          end
+        end
+      end
+
+      def navigate_with_hierarchical_broadcasting(value, indices, template)
+        # Navigate through value with hierarchical broadcasting to match template structure
+        value_depth = calculate_array_depth(value)
+        template_depth = calculate_array_depth(template)
+
+        if value_depth < template_depth
+          # Value is at parent level - broadcast to child level by using fewer indices
+          parent_indices = indices[0, value_depth]
+          navigate_nested_indices(value, parent_indices)
+        else
+          # Same or deeper level - navigate normally
+          navigate_nested_indices(value, indices)
+        end
+      end
+
+      def find_structure_template(all_results)
+        # Find the first array to use as structure template
+        all_results.find { |v| v.is_a?(Array) }
+      end
+
+      def determine_array_length(arrays)
+        # Find the first array and use its length
+        first_array = arrays.find { |v| v.is_a?(Array) }
+        first_array ? first_array.length : 1
+      end
+
+      def extract_element_at_index(value, index)
+        if value.is_a?(Array)
+          index < value.length ? value[index] : nil
+        else
+          value # Scalar value - same for all indices
+        end
+      end
+    end
+  end
+end

data/lib/kumi/core/ruby_parser/dsl_cascade_builder.rb

@@ -22,7 +22,7 @@ module Kumi
           expr = args.last
 
           trait_bindings = convert_trait_names_to_bindings(trait_names, on_loc)
-          condition = create_fn(:all?, trait_bindings)
+          condition = @context.fn(:cascade_and, *trait_bindings)
           result = ensure_syntax(expr)
           add_case(condition, result)
         end
@@ -92,7 +92,7 @@ module Kumi
             when DeclarationReference
               name # Already a binding from method_missing
             else
-              raise_error("trait reference must be a symbol or bare identifier, got #{name.class}", location)
+              raise_error("trait reference must be a bare trait identifier, got #{name.class}", location)
             end
           end
         end

data/lib/kumi/core/ruby_parser/input_builder.rb

@@ -13,13 +13,13 @@ module Kumi
 
         def key(name, type: :any, domain: nil)
           normalized_type = normalize_type(type, name)
-          @context.inputs << Kumi::Syntax::InputDeclaration.new(name, domain, normalized_type, [], loc: @context.current_location)
+          @context.inputs << Kumi::Syntax::InputDeclaration.new(name, domain, normalized_type, [], nil, loc: @context.current_location)
         end
 
         %i[integer float string boolean any scalar].each do |type_name|
           define_method(type_name) do |name, type: nil, domain: nil|
             actual_type = type || (type_name == :scalar ? :any : type_name)
-            @context.inputs << Kumi::Syntax::InputDeclaration.new(name, domain, actual_type, [], loc: @context.current_location)
+            @context.inputs << Kumi::Syntax::InputDeclaration.new(name, domain, actual_type, [], nil, loc: @context.current_location)
           end
         end
 
@@ -40,7 +40,7 @@ module Kumi
         end
 
         def method_missing(method_name, *_args)
-          allowed_methods = "'key', 'integer', 'float', 'string', 'boolean', 'any', 'scalar', 'array', and 'hash'"
+          allowed_methods = "'key', 'integer', 'float', 'string', 'boolean', 'any', 'scalar', 'array', 'hash', and 'element'"
           raise_syntax_error("Unknown method '#{method_name}' in input block. Only #{allowed_methods} are allowed.",
                              location: @context.current_location)
         end
@@ -63,7 +63,7 @@ module Kumi
           elem_type = elem_spec.is_a?(Hash) && elem_spec[:type] ? elem_spec[:type] : :any
 
           array_type = create_array_type(field_name, elem_type)
-          @context.inputs << Kumi::Syntax::InputDeclaration.new(field_name, domain, array_type, [], loc: @context.current_location)
+          @context.inputs << Kumi::Syntax::InputDeclaration.new(field_name, domain, array_type, [], :object, loc: @context.current_location)
         end
 
         def create_array_type(field_name, elem_type)
@@ -81,7 +81,7 @@ module Kumi
           val_type = extract_type(val_spec)
 
           hash_type = create_hash_type(field_name, key_type, val_type)
-          @context.inputs << Kumi::Syntax::InputDeclaration.new(field_name, domain, hash_type, [], loc: @context.current_location)
+          @context.inputs << Kumi::Syntax::InputDeclaration.new(field_name, domain, hash_type, [], nil, loc: @context.current_location)
         end
 
         def extract_type(spec)
@@ -98,14 +98,16 @@ module Kumi
           domain = options[:domain]
 
           # Collect children by creating a nested context
-          children = collect_array_children(&block)
+          children, _, using_elements = collect_array_children(&block)
 
-          # Create the InputDeclaration with children
+          # Create the InputDeclaration with children and access_mode
+          access_mode = using_elements ? :element : :object
           @context.inputs << Kumi::Syntax::InputDeclaration.new(
             field_name,
             domain,
             :array,
             children,
+            access_mode,
             loc: @context.current_location
           )
         end
@@ -119,7 +121,58 @@ module Kumi
           # Execute the block in the nested context
           nested_builder.instance_eval(&block)
 
-          nested_inputs
+          # Determine element type based on what was declared
+          elem_type = determine_element_type(nested_builder, nested_inputs)
+
+          # Check if element() was used
+          using_elements = nested_builder.instance_variable_get(:@using_elements) || false
+
+          [nested_inputs, elem_type, using_elements]
+        end
+
+        def determine_element_type(_builder, inputs)
+          # Since element() always creates named children now,
+          # we just use the standard logic
+          if inputs.any?
+            # If fields were declared, it's a hash/object structure
+            :hash
+          else
+            # No fields declared, default to :any
+            :any
+          end
+        end
+
+        def primitive_element_type?(elem_type)
+          %i[string integer float boolean bool any symbol].include?(elem_type)
+        end
+
+        # New method: element() declaration - always requires a name
+        def element(type_spec, name, &block)
+          @using_elements = true
+          if block_given?
+            # Named element with nested structure: element(:array, :rows) do ... end
+            # These DO set @using_elements to enable element access mode for multi-dimensional arrays
+            case type_spec
+            when :array
+              create_array_field_with_block(name, {}, &block)
+            when :object
+              # Create nested object structure
+              create_object_element(name, &block)
+            else
+              raise_syntax_error("element(#{type_spec.inspect}, #{name.inspect}) with block only supports :array or :object types",
+                                 location: @context.current_location)
+            end
+          else
+            # Named primitive element: element(:boolean, :active)
+            # Only primitive elements mark the parent as using element access
+            @context.inputs << Kumi::Syntax::InputDeclaration.new(name, nil, type_spec, [], nil, loc: @context.current_location)
+          end
+        end
+
+        def create_object_element(name, &block)
+          # Similar to create_array_field_with_block but for objects
+          children, = collect_array_children(&block)
+          @context.inputs << Kumi::Syntax::InputDeclaration.new(name, nil, :object, children, nil, loc: @context.current_location)
         end
       end
     end

data/lib/kumi/core/schema_instance.rb

@@ -39,6 +39,10 @@ module Kumi
         evaluate(key_name)[key_name]
       end
 
+      def functions_used
+        @metadata[:functions_required].to_a
+      end
+
       # Update input values and clear affected cached computations
       def update(**changes)
         changes.each do |field, value|

data/lib/kumi/core/vectorized_function_builder.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Core
+    # Builds vectorized function execution lambdas from analysis metadata
+    class VectorizedFunctionBuilder
+      include NestedStructureUtils
+
+      def self.build_executor(fn_name, compilation_meta, analysis_state)
+        new(fn_name, compilation_meta, analysis_state).build
+      end
+
+      def initialize(fn_name, compilation_meta, analysis_state)
+        @fn_name = fn_name
+        @compilation_meta = compilation_meta
+        @analysis_state = analysis_state
+      end
+
+      def build
+        # Get the function from registry
+        fn = Kumi::Registry.fetch(@fn_name)
+
+        lambda do |arg_values, loc|
+          # Check if any argument is vectorized (array)
+          has_vectorized_args = arg_values.any?(Array)
+
+          if has_vectorized_args
+            # Apply function with broadcasting to all vectorized arguments
+            vectorized_function_call(fn, arg_values)
+          else
+            # All arguments are scalars - regular function call
+            fn.call(*arg_values)
+          end
+        rescue StandardError => e
+          enhanced_message = "Error calling fn(:#{@fn_name}) at #{loc}: #{e.message}"
+          runtime_error = Errors::RuntimeError.new(enhanced_message)
+          runtime_error.set_backtrace(e.backtrace)
+          runtime_error.define_singleton_method(:cause) { e }
+          raise runtime_error
+        end
+      end
+
+      private
+
+      def vectorized_function_call(fn, values)
+        # Find array dimensions for broadcasting
+        array_values = values.select { |v| v.is_a?(Array) }
+        return fn.call(*values) if array_values.empty?
+
+        # Check if we have deeply nested arrays (arrays containing arrays)
+        has_nested_arrays = array_values.any? { |arr| arr.is_a?(Array) && arr.first.is_a?(Array) }
+
+        if has_nested_arrays
+          # Use recursive element-wise operation for nested arrays
+          apply_function_to_nested_structure(fn, values)
+        else
+          # Original flat array logic
+          array_length = array_values.first.size
+          (0...array_length).map do |i|
+            element_args = values.map do |v|
+              v.is_a?(Array) ? v[i] : v # Broadcast scalars
+            end
+            fn.call(*element_args)
+          end
+        end
+      end
+
+      def apply_function_to_nested_structure(fn, values)
+        # Find the first array to determine structure
+        array_value = values.find { |v| v.is_a?(Array) }
+
+        # Apply function element-wise, preserving nested structure
+        map_nested_structure(array_value) do |*indices|
+          element_args = values.map do |value|
+            if value.is_a?(Array)
+              # Navigate to the corresponding element in nested structure
+              navigate_nested_indices(value, indices)
+            else
+              # Scalar - broadcast to all positions
+              value
+            end
+          end
+          fn.call(*element_args)
+        end
+      end
+    end
+  end
+end

data/lib/kumi/errors.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Kumi
   module Errors
     include Core::Errors