kumi 0.0.4 → 0.0.6

data/docs/features/array-broadcasting.md

@@ -0,0 +1,170 @@
+# Array Broadcasting
+
+Automatic vectorization of operations over array fields with element-wise computation and aggregation.
+
+## Overview
+
+The array broadcasting system enables natural field access syntax on array inputs (`input.items.price`) that automatically applies operations element-wise across the array, with intelligent detection of map vs reduce operations.
+
+## Core Mechanism
+
+The system uses a three-stage pipeline:
+
+1. **Parser** - Creates InputElementReference AST nodes for nested field access
+2. **BroadcastDetector** - Identifies which operations should be vectorized vs scalar
+3. **Compiler** - Generates appropriate map/reduce functions based on usage context
+
+## Basic Broadcasting
+
+```ruby
+schema do
+  input do
+    array :line_items do
+      float   :price
+      integer :quantity
+      string  :category
+    end
+    scalar :tax_rate, type: :float
+  end
+
+  # Element-wise computation - broadcasts over each item
+  value :subtotals, input.line_items.price * input.line_items.quantity
+  
+  # Element-wise traits - applied to each item
+  trait :is_taxable, (input.line_items.category != "digital")
+  
+  # Conditional logic - element-wise evaluation
+  value :taxes, fn(:if, is_taxable, subtotals * input.tax_rate, 0.0)
+end
+```
+
+## Aggregation Operations
+
+Operations that consume arrays to produce scalars are automatically detected:
+
+```ruby
+schema do
+  # These aggregate the vectorized results
+  value :total_subtotal, fn(:sum, subtotals)
+  value :total_tax, fn(:sum, taxes)
+  value :grand_total, total_subtotal + total_tax
+  
+  # Statistics over arrays
+  value :avg_price, fn(:avg, input.line_items.price)
+  value :max_quantity, fn(:max, input.line_items.quantity)
+end
+```
+
+## Field Access Nesting
+
+Supports arbitrary depth field access with path building:
+
+```ruby
+schema do
+  input do
+    array :orders do
+      array :items do
+        hash :product do
+          string :name
+          float  :base_price
+        end
+        integer :quantity
+      end
+    end
+  end
+
+  # Deep field access - automatically broadcasts over nested arrays  
+  value :all_product_names, input.orders.items.product.name
+  value :total_values, input.orders.items.product.base_price * input.orders.items.quantity
+end
+```
+
+## Type Inference
+
+The type system automatically infers appropriate types for broadcasted operations:
+
+- `input.items.price` (float array) → inferred as `:float` per element
+- `input.items.price * input.items.quantity` → element-wise `:float` result
+- `fn(:sum, input.items.price)` → scalar `:float` result
+
+## Implementation Details
+
+### Parser Layer
+- **InputFieldProxy** - Handles `input.field.subfield...` with path building
+- **InputElementReference** - AST node representing array field access paths
+
+### Analysis Layer  
+- **BroadcastDetector** - Identifies vectorized vs scalar operations
+- **TypeInferencer** - Infers types for array element access patterns
+
+### Compilation Layer
+- **Automatic Dispatch** - Maps element-wise operations to array map functions
+- **Reduction Detection** - Converts aggregation functions to array reduce operations
+
+## Usage Patterns
+
+### Element-wise Operations
+```ruby
+# All of these broadcast element-wise
+value :discounted_prices, input.items.price * 0.9
+trait :expensive, (input.items.price > 100.0)  
+value :categories, input.items.category
+```
+
+### Aggregation Operations
+```ruby
+# These consume arrays to produce scalars
+value :item_count, fn(:size, input.items)
+value :total_price, fn(:sum, input.items.price)
+value :has_expensive, fn(:any?, expensive)
+```
+
+### Mixed Operations
+```ruby
+# Element-wise computation followed by aggregation
+value :line_totals, input.items.price * input.items.quantity
+value :order_total, fn(:sum, line_totals)
+value :avg_line_total, fn(:avg, line_totals)
+```
+
+## Error Handling
+
+### Dimension Mismatch Detection
+
+Array broadcasting operations are only valid within the same array source. Attempting to broadcast across different arrays generates detailed error messages:
+
+```ruby
+schema do
+  input do
+    array :items do
+      string :name
+    end
+    array :logs do  
+      string :user_name
+    end
+  end
+
+  # This will generate a dimension mismatch error
+  trait :same_name, input.items.name == input.logs.user_name
+end
+
+# Error:
+# Cannot broadcast operation across arrays from different sources: items, logs. 
+# Problem: Multiple operands are arrays from different sources:
+#   - Operand 1 resolves to array(string) from array 'items'
+#   - Operand 2 resolves to array(string) from array 'logs'
+# Direct operations on arrays from different sources is ambiguous and not supported. 
+# Vectorized operations can only work on fields from the same array input.
+```
+
+The error messages provide:
+- **Quick Summary**: Identifies the conflicting array sources
+- **Type Information**: Shows the resolved types of each operand  
+- **Clear Explanation**: Why the operation is ambiguous and not supported
+
+## Performance Characteristics
+
+- **Single Pass** - Each array is traversed once per computation chain
+- **Lazy Evaluation** - Operations are composed into efficient pipelines  
+- **Memory Efficient** - No intermediate array allocations for simple operations
+- **Type Safe** - Full compile-time type checking for array element operations

data/docs/features/input-declaration-system.md

@@ -0,0 +1,42 @@
+# Input Declarations
+
+Declares expected inputs with types and domain constraints, separating input metadata from business logic.
+
+## Declaration Syntax
+
+```ruby
+schema do
+  input do
+    string  :customer_name
+    integer :age, domain: 18..120
+    float   :balance, domain: 0.0..Float::INFINITY
+    boolean :verified
+    array   :tags, elem: { type: :string }
+    hash    :metadata, key: { type: :string }, val: { type: :any }
+    any     :flexible
+  end
+  
+  trait :adult, (input.age >= 18)
+  value :status, input.verified ? "verified" : "pending"
+end
+```
+
+## Domain Constraints
+
+**Validation occurs at runtime:**
+```ruby
+schema.from(credit_score: 900)  # Domain: 300..850
+# => InputValidationError: Field :credit_score value 900 is outside domain 300..850
+```
+
+**Constraint types:**
+- Range domains: `domain: 18..120`
+- Array domains: `domain: %w[active inactive]`
+- Regex domains: `domain: /^[a-zA-Z]+$/`
+
+## Validation Process
+
+- Input data validated against declared field metadata
+- Type validation checks value matches declared type
+- Domain validation checks value satisfies constraints
+- Detailed error messages for violations

data/docs/features/performance.md

@@ -0,0 +1,16 @@
+# Performance
+
+TODO: Add benchmark data
+
+Processes large schemas with optimized algorithms for analysis, compilation, and execution.
+
+## Execution Model
+
+**Compilation:**
+- Each expression compiled to executable lambda
+- Direct function calls for operations
+
+**Runtime:**
+- Result caching to avoid recomputation
+- Selective evaluation: only requested keys computed
+- Direct lambda invocation

data/examples/federal_tax_calculator_2024.rb

@@ -1,28 +1,34 @@
+# frozen_string_literal: true
+
 # U.S. federal income‑tax plus FICA
 
 require_relative "../lib/kumi"
 
-module CompositeTax2024
-  extend Kumi::Schema
+module Tax2024
   FED_BREAKS_SINGLE   = [11_600, 47_150, 100_525, 191_950,
-                         243_725, 609_350, Float::INFINITY]
+                         243_725, 609_350, Float::INFINITY].freeze
 
   FED_BREAKS_MARRIED  = [23_200, 94_300, 201_050, 383_900,
-                         487_450, 731_200, Float::INFINITY]
+                         487_450, 731_200, Float::INFINITY].freeze
 
   FED_BREAKS_SEPARATE = [11_600, 47_150, 100_525, 191_950,
-                         243_725, 365_600, Float::INFINITY]
+                         243_725, 365_600, Float::INFINITY].freeze
 
   FED_BREAKS_HOH      = [16_550, 63_100, 100_500, 191_950,
-                         243_700, 609_350, Float::INFINITY]
-  
+                         243_700, 609_350, Float::INFINITY].freeze
+
   FED_RATES           = [0.10, 0.12, 0.22, 0.24,
-                         0.32, 0.35, 0.37]
+                         0.32, 0.35, 0.37].freeze
+end
+
+module FederalTaxCalculator
+  extend Kumi::Schema
+  include Tax2024
 
   schema do
     input do
       float  :income
-      string :filing_status
+      string :filing_status, domain: %w[single married_joint married_separate head_of_household]
     end
 
     # ── standard deduction table ───────────────────────────────────────
@@ -32,30 +38,28 @@ module CompositeTax2024
     trait :hoh,        input.filing_status == "head_of_household"
 
     value :std_deduction do
-      on  :single,   14_600
-      on  :married,  29_200
-      on  :separate, 14_600
+      on  single,   14_600
+      on  married,  29_200
+      on  separate, 14_600
       base           21_900 # HOH default
     end
 
-    value :taxable_income,
-          fn(:max, [input.income - std_deduction, 0])
+    value :taxable_income, [input.income - std_deduction, 0].max
 
-    # ── FEDERAL brackets (single shown; others similar if needed) ──────
     value :fed_breaks do
-      on  :single,   FED_BREAKS_SINGLE
-      on  :married,  FED_BREAKS_MARRIED
-      on  :separate, FED_BREAKS_SEPARATE
-      on  :hoh,      FED_BREAKS_HOH
+      on  single,   FED_BREAKS_SINGLE
+      on  married,  FED_BREAKS_MARRIED
+      on  separate, FED_BREAKS_SEPARATE
+      on  hoh,      FED_BREAKS_HOH
     end
 
-    value :fed_rates,  FED_RATES
+    value :fed_rates, FED_RATES
     value :fed_calc,
           fn(:piecewise_sum, taxable_income, fed_breaks, fed_rates)
 
     value :fed_tax,       fed_calc[0]
     value :fed_marginal,  fed_calc[1]
-    value :fed_eff,       fed_tax / fn(:max, [input.income, 1.0])
+    value :fed_eff,       fed_tax / [input.income, 1.0].max
 
     # ── FICA (employee share) ─────────────────────────────────────────────
     value :ss_wage_base, 168_600.0
@@ -66,42 +70,37 @@ module CompositeTax2024
 
     # additional‑Medicare threshold depends on filing status
     value :addl_threshold do
-      on  :single,   200_000
-      on  :married,  250_000
-      on  :separate, 125_000
+      on  single,   200_000
+      on  married,  250_000
+      on  separate, 125_000
       base           200_000 # HOH same as single
     end
 
     # social‑security portion (capped)
-    value :ss_tax,
-          fn(:min, [input.income, ss_wage_base]) * ss_rate
+    value :ss_tax, [input.income, ss_wage_base].min * ss_rate
 
     # medicare (1.45 % on everything)
     value :med_tax, input.income * med_base_rate
 
     # additional medicare on income above threshold
-    value :addl_med_tax,
-          fn(:max, [input.income - addl_threshold, 0]) * addl_med_rate
+    value :addl_med_tax, [input.income - addl_threshold, 0].max * addl_med_rate
 
     value :fica_tax,  ss_tax + med_tax + addl_med_tax
-    value :fica_eff,  fica_tax / fn(:max, [input.income, 1.0])
+    value :fica_eff,  fica_tax / [input.income, 1.0].max
 
     # ── Totals ─────────────────────────────────────────────────────────
-    value :total_tax,
-          fed_tax + fica_tax
+    value :total_tax, fed_tax + fica_tax
 
-    value :total_eff,   total_tax / fn(:max, [input.income, 1.0])
-    value :after_tax,   input.income - total_tax
+    value :total_eff, total_tax / fn(:max, [input.income, 1.0])
+    value :after_tax, input.income - total_tax
   end
 end
 
-def example(income: 1_000_000, status: "single")
-  # Create a runner for the schema
-  r = CompositeTax2024.from(income: income, filing_status: status)
-  # puts r.inspect
+def print_tax_summary(args)
+  r = FederalTaxCalculator.from(args)
   puts "\n=== 2024 U.S. Income‑Tax Example ==="
-  printf "Income:                      $%0.2f\n", income
-  puts   "Filing status:               #{status}\n\n"
+  printf "Income:                      $%0.2f\n", args[:income]
+  puts   "Filing status:               #{args[:filing_status]}\n\n"
 
   puts "Federal tax:             $#{r[:fed_tax].round(2)} (#{(r[:fed_eff] * 100).round(2)}% effective)"
   puts "FICA tax:                $#{r[:fica_tax].round(2)} (#{(r[:fica_eff] * 100).round(2)}% effective)"
@@ -109,4 +108,8 @@ def example(income: 1_000_000, status: "single")
   puts "After-tax income:        $#{r[:after_tax].round(2)}"
 end
 
-example
+
+input = {  income: 1_000_000,
+  filing_status: "single"
+}
+print_tax_summary(input)

data/examples/game_of_life.rb

@@ -0,0 +1,97 @@
+$LOAD_PATH.unshift(File.join(__dir__, "..", "lib"))
+require "kumi"
+
+NEIGHBOR_DELTAS = [[-1, -1], [-1, 0], [-1, 1], [0, -1], [0, 1], [1, -1], [1, 0], [1, 1]]
+begin
+  # in a block so we dont define this globally
+  def neighbor_cells_sum_method(cells, row, col, height, width)
+    # Calculate neighbor indices with wraparound
+    NEIGHBOR_DELTAS.map do |dr, dc|
+      neighbor_row = (row + dr) % height
+      neighbor_col = (col + dc) % width
+      neighbor_index = (neighbor_row * width) + neighbor_col
+      cells[neighbor_index]
+    end.sum
+  end
+  Kumi::FunctionRegistry.register_with_metadata(:neighbor_cells_sum, method(:neighbor_cells_sum_method),
+                                                return_type: :integer, arity: 5,
+                                                param_types: %i[array integer integer integer integer],
+                                                description: "Get neighbor cells for Conway's Game of Life")
+end
+
+module GameOfLife
+  extend Kumi::Schema
+  WIDTH = 50
+  HEIGHT = 30
+
+  schema do
+    # Complete Game of Life engine - computes entire next generation
+    input do
+      array :cells, elem: { type: :integer }
+    end
+
+    # Generate next state for every cell in the grid
+    next_cell_values = []
+
+    (0...HEIGHT).each do |row|
+      (0...WIDTH).each do |col|
+        # Neighbor count and current state for this cell
+        cell_index = (row * WIDTH) + col
+        value :"neighbor_sum_#{cell_index}", fn(:neighbor_cells_sum, input.cells, row, col, HEIGHT, WIDTH)
+
+        # Game of Life rules: (alive && neighbors == 2) || (neighbors == 3)
+        trait :"cell_#{cell_index}_alive",
+              ((input.cells[cell_index] == 1) & (ref(:"neighbor_sum_#{cell_index}") == 2)) |
+              (ref(:"neighbor_sum_#{cell_index}") == 3)
+
+        # Next state for this cell
+        value :"cell_#{cell_index}_next" do
+          on :"cell_#{cell_index}_alive", 1
+          base 0
+        end
+
+        next_cell_values << ref(:"cell_#{cell_index}_next")
+      end
+    end
+
+    # Complete next generation as array
+    value :next_cells, next_cell_values
+
+    # Render current state as visual string
+    value :cell_symbols, fn(:map_conditional, input.cells, 1, "█", " ")
+    value :grid_rows, fn(:each_slice, cell_symbols, WIDTH)
+    value :rendered_grid, fn(:map_join_rows, grid_rows, "", "\n")
+  end
+end
+
+# # Helper to pretty‑print the grid
+def render(cells, width)
+  cells.each_slice(width) do |row|
+    puts row.map { |v| v == 1 ? "█" : " " }.join
+  end
+end
+
+# # Bootstrap a simple glider on a 10×10 grid
+width  = GameOfLife::WIDTH
+height = GameOfLife::HEIGHT
+cells  = Array.new(width * height, 0)
+# Glider pattern
+[[1, 1], [2, 3], [3, 1], [3, 2], [3, 3]].each { |r, c| cells[(r * width) + c] = 1 }
+
+10_000.times do |gen|
+  system("clear") || system("cls")
+  puts "Conway's Game of Life - Generation #{gen}"
+  puts ""
+
+  # Create schema instance for this generation
+  runner = GameOfLife.from(cells: cells)
+
+  # Render using Kumi instead of Ruby function!
+  rendered_output = runner[:rendered_grid]
+  puts rendered_output
+
+  # Calculate next generation with single schema call!
+  cells = runner[:next_cells]
+
+  sleep 0.1
+end