kumi 0.0.16 → 0.0.17

data/docs/functions/signatures.md

@@ -1,171 +0,0 @@
-# Function Signatures (NEP 20)
-
-Kumi implements **NEP 20 conformant function signatures** for describing generalized universal functions. This system provides precise control over multidimensional operations with support for fixed-size, flexible, and broadcastable dimensions.
-
-## Basic Syntax
-
-Function signatures use the format: `<inputs> -> <outputs>[@policy]`
-
-```ruby
-"(i),(i)->(i)"           # Element-wise operation on vectors
-"(m,n),(n,p)->(m,p)"     # Matrix multiplication  
-"(i,j)->(i)"             # Reduction along j axis
-"(),()->()"              # Scalar operation
-```
-
-## NEP 20 Extensions
-
-### Fixed-Size Dimensions
-
-Use integers to specify exact dimension sizes:
-
-```ruby
-"(3),(3)->(3)"          # Cross product for 3-vectors
-"()->(2)"               # Function returning 2D vector
-"(),()->(3)"            # Two scalars to 3D vector
-```
-
-Fixed-size dimensions must match exactly - no broadcasting allowed.
-
-### Flexible Dimensions (?)
-
-The `?` modifier indicates dimensions that can be omitted if not present in all operands:
-
-```ruby
-"(m?,n),(n,p?)->(m?,p?)" # matmul signature - handles:
-                         # - (m,n),(n,p) -> (m,p)   matrix * matrix
-                         # - (n),(n,p) -> (p)       vector * matrix  
-                         # - (m,n),(n) -> (m)       matrix * vector
-                         # - (n),(n) -> ()          vector * vector
-```
-
-### Broadcastable Dimensions (|1)
-
-The `|1` modifier allows dimensions to broadcast against scalar or size-1 dimensions:
-
-```ruby
-"(n|1),(n|1)->()"       # all_equal - compares vectors or scalars
-"(i|1),(j|1)->(i,j)"    # Outer product with broadcasting
-```
-
-**Constraints:**
-- Only input dimensions can be broadcastable
-- Output dimensions cannot have `|1` modifier
-- Cannot combine `?` and `|1` on same dimension
-
-## Join Policies
-
-Control how different dimension names are combined:
-
-### Default (nil policy)
-All non-scalar arguments must have compatible dimension names:
-```ruby
-"(i),(i)->(i)"     # ✓ Compatible - same dimensions
-"(i),(j)->(i,j)"   # ✗ Incompatible without policy
-```
-
-### @product Policy
-Allows different dimensions, creates Cartesian product:
-```ruby
-"(i),(j)->(i,j)@product"  # Outer product
-```
-
-### @zip Policy  
-Allows different dimensions, pairs them up:
-```ruby
-"(i),(j)->(i)@zip"        # Paired operation
-```
-
-## Examples from NEP 20
-
-| Signature | Use Case | Description |
-|-----------|----------|-------------|
-| `(),()->()` | Addition | Scalar operations |
-| `(i)->()` | Sum | Reduction over last axis |
-| `(i\|1),(i\|1)->()` | all_equal | Equality test with broadcasting |
-| `(i),(i)->()` | dot product | Inner vector product |
-| `(m,n),(n,p)->(m,p)` | matmul | Matrix multiplication |
-| `(3),(3)->(3)` | cross | Cross product for 3-vectors |
-| `(m?,n),(n,p?)->(m?,p?)` | matmul | Universal matrix operations |
-
-## Signature Validation Rules
-
-1. **Arity matching**: Number of arguments must match signature
-2. **Fixed-size consistency**: Integer dimensions must match exactly
-3. **Broadcasting rules**: `|1` dimensions can broadcast to any size
-4. **Flexible resolution**: `?` dimensions resolved based on presence
-5. **Output constraints**: No broadcastable (`|1`) dimensions in outputs
-6. **Policy requirements**: Different dimension names need explicit policy
-
-## Matching Priority
-
-When multiple signatures are available, resolution prefers:
-
-1. **Exact matches** (score: 0) - All dimensions match perfectly
-2. **Fixed-size matches** (score: 0-2) - Integer dimensions match
-3. **Broadcast matches** (score: 1-3) - Scalar broadcasting  
-4. **Flexible matches** (score: 10+) - Dimension omission/addition
-
-Lower scores indicate better matches.
-
-## Implementation Notes
-
-Signatures are parsed into `Dimension` objects that track:
-- Name (Symbol or Integer)
-- Flexible flag (`?`)
-- Broadcastable flag (`|1`)
-
-The resolver handles NEP 20 semantics including:
-- Flexible dimension resolution
-- Broadcastable matching
-- Fixed-size validation
-- Join policy enforcement
-
-## Constraint Solver
-
-Kumi implements a **dimension constraint solver** that validates cross-argument dimension consistency for operations like matrix multiplication:
-
-```ruby
-signature = "(m,n),(n,p)->(m,p)"
-arg_shapes = [[:m, :n], [:n, :p]]
-
-# The solver validates that 'n' dimensions are consistent across arguments
-plan = resolver.choose(signatures: [sig], arg_shapes: arg_shapes)
-# Returns: { env: { m: :m, n: :n, p: :p }, result_axes: [:m, :p] }
-```
-
-The constraint solver:
-- Links repeated dimension names across arguments
-- Validates dimension consistency (same `n` in both positions)
-- Returns dimension environment bindings
-- Enables complex operations without explicit join policies
-
-## Integration with Analyzer
-
-Function signatures integrate with Kumi's analyzer pipeline through:
-
-### FunctionSignaturePass
-Resolves NEP-20 signatures for all function calls and attaches metadata:
-- `:result_axes` - Output dimension names
-- `:join_policy` - Cross-dimensional operation policy  
-- `:dropped_axes` - Dimensions eliminated by reductions
-- `:effective_signature` - Normalized signature for lowering
-- `:dim_env` - Dimension variable bindings
-- `:shape_contract` - Simplified contract for lowering
-
-### Node Index Architecture
-The analyzer creates a node index mapping `object_id → metadata` that passes can use to:
-- Attach signature resolution results
-- Share metadata across analysis passes
-- Validate consistency in lowering
-
-## Feature Flags
-
-Control NEP-20 extensions with environment variables:
-
-```bash
-KUMI_ENABLE_FLEX=1    # Enable flexible dimension matching (?)
-KUMI_ENABLE_BCAST1=1  # Enable broadcastable dimension matching (|1)
-```
-
-For more details see [NEP 20 specification](https://numpy.org/neps/nep-0020-expansion-of-generalized-ufunc-signatures.html).

data/examples/hash_objects_demo.rb

@@ -1,138 +0,0 @@
-# frozen_string_literal: true
-
-# Hash Objects Demo - Demonstrates Kumi's structured input syntax
-# This example shows how to use hash objects for organizing related input fields
-
-require_relative "../lib/kumi"
-
-module HashObjectsDemo
-  extend Kumi::Schema
-
-  schema do
-    input do
-      # Employee information as hash object
-      hash :employee do
-        string :name
-        integer :age, domain: 18..65
-        float :base_salary, domain: 30_000.0..200_000.0
-        boolean :is_manager
-        integer :years_experience, domain: 0..40
-      end
-      
-      # Company configuration as hash object
-      hash :company_config do
-        string :name
-        float :bonus_percentage, domain: 0.0..0.50
-        float :manager_multiplier, domain: 1.0..2.0
-        integer :current_year, domain: 2020..2030
-      end
-      
-      # Benefits configuration as hash object
-      hash :benefits do
-        boolean :health_insurance
-        boolean :dental_coverage
-        float :retirement_match, domain: 0.0..0.10
-        integer :vacation_days, domain: 10..30
-      end
-    end
-
-    # Traits using hash object access
-    trait :is_senior, input.employee.years_experience >= 5
-    trait :eligible_for_bonus, is_senior & input.employee.is_manager
-    trait :has_full_benefits, input.benefits.health_insurance & input.benefits.dental_coverage
-
-    # Salary calculations using structured data
-    value :base_annual_salary, input.employee.base_salary
-    
-    value :bonus_amount do
-      on eligible_for_bonus, base_annual_salary * input.company_config.bonus_percentage
-      base 0.0
-    end
-    
-    trait :is_manager_trait, input.employee.is_manager == true
-    
-    value :manager_adjustment do
-      on is_manager_trait, input.company_config.manager_multiplier
-      base 1.0
-    end
-    
-    value :total_compensation, (base_annual_salary * manager_adjustment) + bonus_amount
-    
-    # Benefits calculations
-    value :retirement_contribution, total_compensation * input.benefits.retirement_match
-    
-    value :benefits_package_value do
-      on has_full_benefits, 5_000.0 + input.benefits.vacation_days * 150.0
-      base input.benefits.vacation_days * 100.0
-    end
-    
-    # Final totals
-    value :total_package_value, total_compensation + retirement_contribution + benefits_package_value
-    
-    # Summary calculations
-    value :years_to_retirement, 65 - input.employee.age
-  end
-end
-
-# Example usage
-if __FILE__ == $0
-  puts "Hash Objects Demo - Employee Compensation Calculator"
-  puts "=" * 55
-
-  # Sample data demonstrating hash objects structure
-  employee_data = {
-    employee: {
-      name: "Alice Johnson",
-      age: 32,
-      base_salary: 85_000.0,
-      is_manager: true,
-      years_experience: 8
-    },
-    company_config: {
-      name: "Tech Solutions Inc",
-      bonus_percentage: 0.15,
-      manager_multiplier: 1.25,
-      current_year: 2024
-    },
-    benefits: {
-      health_insurance: true,
-      dental_coverage: true,
-      retirement_match: 0.06,
-      vacation_days: 25
-    }
-  }
-
-  # Calculate compensation
-  result = HashObjectsDemo.from(employee_data)
-  
-  def format_currency(amount)
-    "$#{amount.round(0).to_s.gsub(/\B(?=(\d{3})+(?!\d))/, ',')}"
-  end
-  
-  puts "\nEmployee Information:"
-  puts "- Name: #{employee_data[:employee][:name]}"
-  puts "- Age: #{employee_data[:employee][:age]}"
-  puts "- Experience: #{employee_data[:employee][:years_experience]} years"
-  puts "- Manager: #{employee_data[:employee][:is_manager] ? 'Yes' : 'No'}"
-  
-  puts "\nCompany: #{employee_data[:company_config][:name]}"
-  puts "- Bonus Rate: #{(employee_data[:company_config][:bonus_percentage] * 100).round(1)}%"
-  puts "- Manager Multiplier: #{employee_data[:company_config][:manager_multiplier]}x"
-  
-  puts "\nBenefits:"
-  puts "- Health Insurance: #{employee_data[:benefits][:health_insurance] ? 'Yes' : 'No'}"
-  puts "- Dental Coverage: #{employee_data[:benefits][:dental_coverage] ? 'Yes' : 'No'}"
-  puts "- Retirement Match: #{(employee_data[:benefits][:retirement_match] * 100).round(1)}%"
-  puts "- Vacation Days: #{employee_data[:benefits][:vacation_days]}"
-
-  puts "\nCompensation Breakdown:"
-  puts "- Base Salary: #{format_currency(result[:base_annual_salary])}"
-  puts "- Manager Adjustment: #{result[:manager_adjustment]}x"
-  puts "- Bonus: #{format_currency(result[:bonus_amount])}"
-  puts "- Total Compensation: #{format_currency(result[:total_compensation])}"
-  puts "- Retirement Contribution: #{format_currency(result[:retirement_contribution])}"
-  puts "- Benefits Package Value: #{format_currency(result[:benefits_package_value])}"
-  
-  puts "\nTotal Package: #{format_currency(result[:total_package_value])}"
-  puts "Years to Retirement: #{result[:years_to_retirement]}"
-end

data/lib/kumi/core/analyzer/passes/function_signature_pass.rb

@@ -1,199 +0,0 @@
-# frozen_string_literal: true
-
-module Kumi
-  module Core
-    module Analyzer
-      module Passes
-        # RESPONSIBILITY: Apply NEP-20 signature resolution to function calls
-        # DEPENDENCIES: :node_index from Toposorter, :broadcast_metadata (optional)
-        # PRODUCES: Signature metadata in node_index for CallExpression nodes
-        # INTERFACE: new(schema, state).run(errors)
-        class FunctionSignaturePass < PassBase
-          def run(errors)
-            node_index = get_state(:node_index, required: true)
-
-            # Process all CallExpression nodes in the index
-            node_index.each do |object_id, entry|
-              next unless entry[:type] == "CallExpression"
-
-              resolve_function_signature(entry, object_id, errors)
-            end
-
-            state # Node index is modified in-place
-          end
-
-          private
-
-          def resolve_function_signature(entry, object_id, errors)
-            node = entry[:node]
-
-            # 1) Gather candidate signatures from current registry
-            sig_strings = get_function_signatures(node)
-            return if sig_strings.empty?
-
-            begin
-              sigs = parse_signatures(sig_strings)
-            rescue Kumi::Core::Functions::SignatureError => e
-              report_error(errors, "Invalid signature for function `#{node.fn_name}`: #{e.message}",
-                           location: node.loc, type: :type)
-              return
-            end
-
-            # 2) Build arg_shapes from current node context
-            arg_shapes = build_argument_shapes(node, object_id)
-
-            # 3) Resolve signature
-            begin
-              plan = Kumi::Core::Functions::SignatureResolver.choose(signatures: sigs, arg_shapes: arg_shapes)
-            rescue Kumi::Core::Functions::SignatureMatchError => e
-              report_error(errors, 
-                          "Signature mismatch for `#{node.fn_name}` with args #{format_shapes(arg_shapes)}. Candidates: #{format_sigs(sig_strings)}. #{e.message}",
-                          location: node.loc, type: :type)
-              return
-            end
-
-            # 4) Attach metadata to node index entry
-            attach_signature_metadata(entry, plan)
-          end
-
-          def get_function_signatures(node)
-            # Use RegistryV2 if enabled, otherwise fall back to legacy registry
-            if registry_v2_enabled?
-              registry_v2_signatures(node)
-            else
-              legacy_registry_signatures(node)
-            end
-          end
-
-          def registry_v2_signatures(node)
-            registry_v2.get_function_signatures(node.fn_name)
-          rescue => e
-            # If RegistryV2 fails, fall back to legacy
-            legacy_registry_signatures(node)
-          end
-
-          def legacy_registry_signatures(node)
-            # Try to get signatures from the current registry
-            # For now, we'll create basic signatures from the current registry format
-
-            meta = Kumi::Registry.signature(node.fn_name)
-
-            # Check if the function already has NEP-20 signatures
-            return meta[:signatures] if meta[:signatures] && meta[:signatures].is_a?(Array)
-
-            # Otherwise, create a basic signature from arity
-            # This is a bridge until we have full NEP-20 signatures in the registry
-            create_basic_signature(meta[:arity])
-          rescue Kumi::Errors::UnknownFunction
-            # For now, return empty array - function existence will be caught by TypeChecker
-            []
-          end
-
-          def create_basic_signature(arity)
-            return [] if arity.nil? || arity < 0 # Variable arity - skip for now
-
-            case arity
-            when 0
-              ["()->()"] # Scalar function
-            when 1
-              ["()->()", "(i)->(i)"] # Scalar or element-wise
-            when 2
-              ["(),()->()", "(i),(i)->(i)"] # Scalar or element-wise binary
-            else
-              # For higher arity, just provide scalar signature
-              args = (["()"] * arity).join(",")
-              ["#{args}->()"]
-            end
-          end
-
-          def build_argument_shapes(node, object_id)
-            # Build argument shapes from current analysis context
-            node.args.map do |arg|
-              axes = get_broadcast_metadata(arg.object_id)
-              normalize_shape(axes)
-            end
-          end
-
-          def normalize_shape(axes)
-            case axes
-            when nil
-              [] # scalar
-            when Array
-              axes.map { |d| d.is_a?(Integer) ? d : d.to_sym }
-            else
-              [] # defensive fallback
-            end
-          end
-
-          def get_broadcast_metadata(arg_object_id)
-            # Try to get broadcast metadata from existing analysis state
-            broadcast_meta = get_state(:broadcast_metadata, required: false)
-            return nil unless broadcast_meta
-
-            # Look up by node object_id
-            broadcast_meta[arg_object_id]&.dig(:axes)
-          end
-
-          def parse_signatures(sig_strings)
-            @sig_cache ||= {}
-            sig_strings.map do |s|
-              @sig_cache[s] ||= Kumi::Core::Functions::SignatureParser.parse(s)
-            end
-          end
-
-          def format_shapes(shapes)
-            shapes.map { |ax| "(#{ax.join(',')})" }.join(', ')
-          end
-
-          def format_sigs(sig_strings)
-            sig_strings.join(" | ")
-          end
-
-          def attach_signature_metadata(entry, plan)
-            # Attach signature resolution results to the node index entry
-            # This way other passes can access the metadata via the node index
-            metadata = entry[:metadata]
-
-            attach_core_signature_data(metadata, plan)
-            attach_shape_contract(metadata, plan)
-          end
-
-          def attach_core_signature_data(metadata, plan)
-            metadata[:signature]           = plan[:signature]
-            metadata[:result_axes]         = plan[:result_axes]        # e.g., [:i, :j]
-            metadata[:join_policy]         = plan[:join_policy]        # nil | :zip | :product
-            metadata[:dropped_axes]        = plan[:dropped_axes]       # e.g., [:j] for reductions
-            metadata[:effective_signature] = plan[:effective_signature] # Normalized for lowering
-            metadata[:dim_env]             = plan[:env]                # Dimension bindings (for matmul)
-            metadata[:signature_score]     = plan[:score]              # Match quality
-          end
-
-          def attach_shape_contract(metadata, plan)
-            # Attach shape contract for lowering convenience
-            metadata[:shape_contract] = {
-              in:   plan[:effective_signature][:in_shapes],
-              out:  plan[:effective_signature][:out_shape],
-              join: plan[:effective_signature][:join_policy]
-            }
-          end
-
-          def registry_v2_enabled?
-            ENV["KUMI_FN_REGISTRY_V2"] == "1"
-          end
-
-          def registry_v2
-            @registry_v2 ||= Kumi::Core::Functions::RegistryV2.load_from_file
-          end
-
-          def nep20_flex_enabled?
-            ENV["KUMI_ENABLE_FLEX"] == "1"
-          end
-
-          def nep20_bcast1_enabled?
-            ENV["KUMI_ENABLE_BCAST1"] == "1"
-          end
-        end
-      end
-    end
-  end
-end

data/lib/kumi/core/analyzer/passes/type_consistency_checker.rb

@@ -1,48 +0,0 @@
-# frozen_string_literal: true
-
-module Kumi
-  module Core
-    module Analyzer
-      module Passes
-        # RESPONSIBILITY: Validate consistency between declared and inferred types
-        # DEPENDENCIES: :input_metadata from InputCollector, :inferred_types from TypeInferencerPass
-        # PRODUCES: None (validation only)
-        # INTERFACE: new(schema, state).run(errors)
-        class TypeConsistencyChecker < PassBase
-          def run(errors)
-            input_meta = get_state(:input_metadata, required: false) || {}
-
-            # First, validate that all declared types are valid
-            validate_declared_types(input_meta, errors)
-
-            # Then check basic consistency (placeholder for now)
-            # In a full implementation, this would do sophisticated usage analysis
-            state
-          end
-
-          private
-
-          def validate_declared_types(input_meta, errors)
-            input_meta.each do |field_name, meta|
-              declared_type = meta[:type]
-              next unless declared_type # Skip fields without declared types
-              next if Kumi::Core::Types.valid_type?(declared_type)
-
-              # Find the input field declaration for proper location information
-              field_decl = find_input_field_declaration(field_name)
-              location = field_decl&.loc
-
-              report_type_error(errors, "Invalid type declaration for field :#{field_name}: #{declared_type.inspect}", location: location)
-            end
-          end
-
-          def find_input_field_declaration(field_name)
-            return nil unless schema
-
-            schema.inputs.find { |input_decl| input_decl.name == field_name }
-          end
-        end
-      end
-    end
-  end
-end

data/lib/kumi/core/functions/dimension.rb

@@ -1,98 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "errors"
-
-module Kumi
-  module Core
-    module Functions
-      # Represents a single dimension in a signature with NEP 20 support.
-      #
-      # A dimension can be:
-      # - Named dimension (symbol): :i, :j, :n
-      # - Fixed-size dimension (integer): 2, 3, 10
-      # - With modifiers:
-      #   - flexible (?): can be omitted if not present in all operands
-      #   - broadcastable (|1): can broadcast against size-1 dimensions
-      #
-      # Examples:
-      #   Dimension.new(:i)           # named dimension 'i'
-      #   Dimension.new(3)            # fixed-size dimension of size 3
-      #   Dimension.new(:n, flexible: true)      # dimension 'n' that can be omitted
-      #   Dimension.new(:i, broadcastable: true) # dimension 'i' that can broadcast
-      class Dimension
-        attr_reader :name, :flexible, :broadcastable
-
-        def initialize(name, flexible: false, broadcastable: false)
-          @name = name
-          @flexible = flexible
-          @broadcastable = broadcastable
-
-          validate!
-          freeze
-        end
-
-        def fixed_size?
-          @name.is_a?(Integer)
-        end
-
-        def named?
-          @name.is_a?(Symbol)
-        end
-
-        def flexible?
-          @flexible
-        end
-
-        def broadcastable?
-          @broadcastable
-        end
-
-        def size
-          fixed_size? ? @name : nil
-        end
-
-        def ==(other)
-          other.is_a?(Dimension) &&
-            name == other.name &&
-            flexible == other.flexible &&
-            broadcastable == other.broadcastable
-        end
-
-        def eql?(other)
-          self == other
-        end
-
-        def hash
-          [name, flexible, broadcastable].hash
-        end
-
-        def to_s
-          str = name.to_s
-          str += "?" if flexible?
-          str += "|1" if broadcastable?
-          str
-        end
-
-        def inspect
-          "#<Dimension #{self}>"
-        end
-
-        private
-
-        def validate!
-          unless name.is_a?(Symbol) || name.is_a?(Integer)
-            raise SignatureError, "dimension name must be a symbol or integer, got: #{name.inspect}"
-          end
-
-          raise SignatureError, "fixed-size dimension must be positive, got: #{name}" if name.is_a?(Integer) && name <= 0
-
-          raise SignatureError, "dimension cannot be both flexible and broadcastable" if flexible? && broadcastable?
-
-          return unless fixed_size? && flexible?
-
-          raise SignatureError, "fixed-size dimension cannot be flexible"
-        end
-      end
-    end
-  end
-end

data/lib/kumi/core/functions/dtypes.rb

@@ -1,20 +0,0 @@
-module Kumi::Core::Functions
-  DType = Struct.new(:name, keyword_init: true)
-  module DTypes
-    BOOL = DType.new(name: :bool)
-    INT = DType.new(name: :int)
-    FLOAT = DType.new(name: :float)
-    STRING = DType.new(name: :string)
-    DATETIME = DType.new(name: :datetime)
-    ANY = DType.new(name: :any)
-  end
-
-  module Promotion
-    # super simple table; extend later
-    TABLE = {
-      %i[int int] => :int,  %i[int float] => :float, %i[float int] => :float, %i[float float] => :float,
-      %i[bool int] => :int, %i[bool float] => :float, %i[bool bool] => :bool
-    }
-    def self.promote(a, b) = TABLE[[a, b]] || TABLE[[b, a]] || :any
-  end
-end

data/lib/kumi/core/functions/errors.rb

@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-module Kumi
-  module Core
-    module Functions
-      class SignatureError < StandardError; end
-      class SignatureParseError < SignatureError; end
-      class SignatureMatchError < SignatureError; end
-    end
-  end
-end