kumi 0.0.0 → 0.0.4

data/documents/FUNCTIONS.md

@@ -0,0 +1,132 @@
+# Kumi Standard Function Library Reference
+
+Kumi provides a rich library of built-in functions for use within `value` and `trait` expressions via `fn(...)`.
+
+## Logical Functions
+
+* **`all?`**: Check if all elements in collection are truthy
+  * **Usage**: `fn(:all?, array(any) arg1)` → `boolean`
+* **`and`**: Logical AND of multiple conditions
+  * **Usage**: `fn(:and, boolean1, boolean2, ...)` → `boolean`
+* **`any?`**: Check if any element in collection is truthy
+  * **Usage**: `fn(:any?, array(any) arg1)` → `boolean`
+* **`none?`**: Check if no elements in collection are truthy
+  * **Usage**: `fn(:none?, array(any) arg1)` → `boolean`
+* **`not`**: Logical NOT
+  * **Usage**: `fn(:not, boolean arg1)` → `boolean`
+* **`or`**: Logical OR of multiple conditions
+  * **Usage**: `fn(:or, boolean1, boolean2, ...)` → `boolean`
+
+## Comparison Functions
+
+* **`!=`**: Inequality comparison
+  * **Usage**: `fn(:!=, any arg1, any arg2)` → `boolean`
+* **`<`**: Less than comparison
+  * **Usage**: `fn(:<, float arg1, float arg2)` → `boolean`
+* **`<=`**: Less than or equal comparison
+  * **Usage**: `fn(:<=, float arg1, float arg2)` → `boolean`
+* **`==`**: Equality comparison
+  * **Usage**: `fn(:==, any arg1, any arg2)` → `boolean`
+* **`>`**: Greater than comparison
+  * **Usage**: `fn(:>, float arg1, float arg2)` → `boolean`
+* **`>=`**: Greater than or equal comparison
+  * **Usage**: `fn(:>=, float arg1, float arg2)` → `boolean`
+* **`between?`**: Check if value is between min and max
+  * **Usage**: `fn(:between?, float arg1, float arg2, float arg3)` → `boolean`
+
+## Math Functions
+
+* **`abs`**: Absolute value
+  * **Usage**: `fn(:abs, float arg1)` → `float`
+* **`add`**: Add two numbers
+  * **Usage**: `fn(:add, float arg1, float arg2)` → `float`
+* **`ceil`**: Ceiling of number
+  * **Usage**: `fn(:ceil, float arg1)` → `integer`
+* **`clamp`**: Clamp value between min and max
+  * **Usage**: `fn(:clamp, float arg1, float arg2, float arg3)` → `float`
+* **`divide`**: Divide first number by second
+  * **Usage**: `fn(:divide, float arg1, float arg2)` → `float`
+* **`floor`**: Floor of number
+  * **Usage**: `fn(:floor, float arg1)` → `integer`
+* **`modulo`**: Modulo operation
+  * **Usage**: `fn(:modulo, float arg1, float arg2)` → `float`
+* **`multiply`**: Multiply two numbers
+  * **Usage**: `fn(:multiply, float arg1, float arg2)` → `float`
+* **`power`**: Raise first number to power of second
+  * **Usage**: `fn(:power, float arg1, float arg2)` → `float`
+* **`round`**: Round number to specified precision
+  * **Usage**: `fn(:round, float1, float2, ...)` → `float`
+* **`subtract`**: Subtract second number from first
+  * **Usage**: `fn(:subtract, float arg1, float arg2)` → `float`
+* **`piecewise_sum`**: Accumulate over tiered ranges; returns [sum, marginal_rate]
+  * **Usage**: `fn(:piecewise_sum, float arg1, array(float) arg2, array(float) arg3)` → `array(float)`
+
+## String Functions
+
+* **`capitalize`**: Capitalize first letter of string
+  * **Usage**: `fn(:capitalize, string arg1)` → `string`
+* **`concat`**: Concatenate multiple strings
+  * **Usage**: `fn(:concat, string1, string2, ...)` → `string`
+* **`downcase`**: Convert string to lowercase
+  * **Usage**: `fn(:downcase, string arg1)` → `string`
+* **`end_with?`**: Check if string ends with suffix
+  * **Usage**: `fn(:end_with?, string arg1, string arg2)` → `boolean`
+* **`include?`**: Check if collection includes element
+  * **Usage**: `fn(:include?, array(any) arg1, any arg2)` → `boolean`
+* **`length`**: Get collection length
+  * **Usage**: `fn(:length, array(any) arg1)` → `integer`
+* **`start_with?`**: Check if string starts with prefix
+  * **Usage**: `fn(:start_with?, string arg1, string arg2)` → `boolean`
+* **`strip`**: Remove leading and trailing whitespace
+  * **Usage**: `fn(:strip, string arg1)` → `string`
+* **`upcase`**: Convert string to uppercase
+  * **Usage**: `fn(:upcase, string arg1)` → `string`
+
+## Collection Functions
+
+* **`empty?`**: Check if collection is empty
+  * **Usage**: `fn(:empty?, array(any) arg1)` → `boolean`
+* **`first`**: Get first element of collection
+  * **Usage**: `fn(:first, array(any) arg1)` → `any`
+* **`include?`**: Check if collection includes element
+  * **Usage**: `fn(:include?, array(any) arg1, any arg2)` → `boolean`
+* **`last`**: Get last element of collection
+  * **Usage**: `fn(:last, array(any) arg1)` → `any`
+* **`length`**: Get collection length
+  * **Usage**: `fn(:length, array(any) arg1)` → `integer`
+* **`max`**: Find maximum value in numeric collection
+  * **Usage**: `fn(:max, array(float) arg1)` → `float`
+* **`min`**: Find minimum value in numeric collection
+  * **Usage**: `fn(:min, array(float) arg1)` → `float`
+* **`reverse`**: Reverse collection order
+  * **Usage**: `fn(:reverse, array(any) arg1)` → `array(any)`
+* **`size`**: Get collection size
+  * **Usage**: `fn(:size, array(any) arg1)` → `integer`
+* **`sort`**: Sort collection
+  * **Usage**: `fn(:sort, array(any) arg1)` → `array(any)`
+* **`sum`**: Sum all numeric elements in collection
+  * **Usage**: `fn(:sum, array(float) arg1)` → `float`
+* **`unique`**: Remove duplicate elements from collection
+  * **Usage**: `fn(:unique, array(any) arg1)` → `array(any)`
+
+## Conditional Functions
+
+* **`coalesce`**: Return first non-nil value
+  * **Usage**: `fn(:coalesce, any1, any2, ...)` → `any`
+* **`conditional`**: Ternary conditional operator
+  * **Usage**: `fn(:conditional, boolean arg1, any arg2, any arg3)` → `any`
+* **`if`**: If-then-else conditional
+  * **Usage**: `fn(:if, boolean1, boolean2, ...)` → `any`
+
+## Type & Hash Functions
+
+* **`at`**: Get element at index from array
+  * **Usage**: `fn(:at, array(any) arg1, integer arg2)` → `any`
+* **`fetch`**: Fetch value from hash with optional default
+  * **Usage**: `fn(:fetch, hash(any, any)1, hash(any, any)2, ...)` → `any`
+* **`has_key?`**: Check if hash has the given key
+  * **Usage**: `fn(:has_key?, hash(any, any) arg1, any arg2)` → `boolean`
+* **`keys`**: Get all keys from hash
+  * **Usage**: `fn(:keys, hash(any, any) arg1)` → `array(any)`
+* **`values`**: Get all values from hash
+  * **Usage**: `fn(:values, hash(any, any) arg1)` → `array(any)`

data/documents/SYNTAX.md

@@ -0,0 +1,367 @@
+# Kumi DSL Syntax Reference
+
+This document provides a comprehensive comparison of Kumi's DSL syntax showing both the sugar syntax (convenient, readable) and the underlying sugar-free syntax (explicit function calls).
+
+## Table of Contents
+
+- [Schema Structure](#schema-structure)
+- [Input Declarations](#input-declarations)
+- [Value Declarations](#value-declarations)
+- [Trait Declarations](#trait-declarations)
+- [Expressions](#expressions)
+- [Functions](#functions)
+- [Cascade Logic](#cascade-logic)
+- [References](#references)
+
+## Schema Structure
+
+### Basic Schema Template
+
+```ruby
+# With Sugar (Recommended)
+module MySchema
+  extend Kumi::Schema
+
+  schema do
+    input do
+      # Input field declarations
+    end
+
+    # Traits and values using sugar syntax
+  end
+end
+
+# Sugar-Free (Explicit)
+module MySchema
+  extend Kumi::Schema
+
+  schema do
+    input do
+      # Input field declarations (same)
+    end
+
+    # Traits and values using explicit function calls
+  end
+end
+```
+
+## Input Declarations
+
+Input declarations are the same in both syntaxes:
+
+```ruby
+input do
+  # Type-specific declarations
+  integer :age, domain: 18..65
+  string :status, domain: %w[active inactive suspended]
+  float :score, domain: 0.0..100.0
+  array :tags, elem: { type: :string }
+  hash :metadata, key: { type: :string }, val: { type: :any }
+  
+  # Untyped fields
+  any :misc_data
+end
+```
+
+## Value Declarations
+
+### Arithmetic Operations
+
+```ruby
+# With Sugar
+value :total_score, input.math_score + input.verbal_score + input.writing_score
+value :average_score, total_score / 3
+value :scaled_score, average_score * 1.5
+value :final_score, scaled_score - input.penalty_points
+
+# Sugar-Free
+value :total_score, fn(:add, fn(:add, input.math_score, input.verbal_score), input.writing_score)
+value :average_score, fn(:divide, total_score, 3)
+value :scaled_score, fn(:multiply, average_score, 1.5)
+value :final_score, fn(:subtract, scaled_score, input.penalty_points)
+```
+
+### Mathematical Functions
+
+```ruby
+# With Sugar (Note: Some functions require sugar-free syntax)
+value :score_variance, fn(:power, fn(:subtract, input.score, average_score), 2)
+value :max_possible, fn(:max, [input.math_score, input.verbal_score, input.writing_score])
+value :min_score, fn(:min, [input.math_score, input.verbal_score])
+
+# Sugar-Free
+value :score_variance, fn(:power, fn(:subtract, input.score, average_score), 2)
+value :max_possible, fn(:max, [input.math_score, input.verbal_score, input.writing_score])
+value :min_score, fn(:min, [input.math_score, input.verbal_score])
+```
+
+## Trait Declarations
+
+### Comparison Operations
+
+```ruby
+# With Sugar
+trait :high_scorer, input.total_score >= 1400
+trait :perfect_math, input.math_score == 800
+trait :needs_improvement, input.total_score < 1000
+trait :above_average, input.average_score > 500
+
+# Sugar-Free
+trait :high_scorer, fn(:>=, input.total_score, 1400)
+trait :perfect_math, fn(:==, input.math_score, 800)
+trait :needs_improvement, fn(:<, input.total_score, 1000)
+trait :above_average, fn(:>, input.average_score, 500)
+```
+
+### Logical Operations
+
+```ruby
+# With Sugar
+trait :excellent_student, high_scorer & perfect_math
+trait :qualified, (input.age >= 18) & (input.score >= 1200) & (input.status == "active")
+trait :needs_review, needs_improvement & (input.attempts > 2)
+
+# Sugar-Free
+trait :excellent_student, fn(:and, high_scorer, perfect_math)
+trait :qualified, fn(:and, fn(:and, fn(:>=, input.age, 18), fn(:>=, input.score, 1200)), fn(:==, input.status, "active"))
+trait :needs_review, fn(:and, needs_improvement, fn(:>, input.attempts, 2))
+```
+
+### String Operations
+
+```ruby
+# With Sugar  
+trait :long_name, input.name.length > 20
+trait :starts_with_a, input.name.start_with?("A")
+trait :contains_space, input.name.include?(" ")
+
+# Sugar-Free
+trait :long_name, fn(:>, fn(:string_length, input.name), 20)
+trait :starts_with_a, fn(:start_with?, input.name, "A")
+trait :contains_space, fn(:contains?, input.name, " ")
+```
+
+## Expressions
+
+### Complex Expressions
+
+```ruby
+# With Sugar
+value :weighted_score, (input.math_score * 0.4) + (input.verbal_score * 0.3) + (input.writing_score * 0.3)
+value :percentile_rank, ((scored_better_than / total_students) * 100).round(2)
+
+# Sugar-Free
+value :weighted_score, fn(:add, 
+  fn(:add, 
+    fn(:multiply, input.math_score, 0.4), 
+    fn(:multiply, input.verbal_score, 0.3)
+  ), 
+  fn(:multiply, input.writing_score, 0.3)
+)
+value :percentile_rank, fn(:round, 
+  fn(:multiply, 
+    fn(:divide, scored_better_than, total_students), 
+    100
+  ), 
+  2
+)
+```
+
+### Collection Operations
+
+```ruby
+# With Sugar
+value :total_scores, input.score_array.sum
+value :score_count, input.score_array.size
+value :unique_scores, input.score_array.uniq.size
+value :sorted_scores, input.score_array.sort
+
+# Sugar-Free
+value :total_scores, fn(:sum, input.score_array)
+value :score_count, fn(:size, input.score_array)
+value :unique_scores, fn(:size, fn(:unique, input.score_array))
+value :sorted_scores, fn(:sort, input.score_array)
+```
+
+## Functions
+
+### Built-in Functions Available
+
+| Category | Sugar | Sugar-Free |
+|----------|-------|------------|
+| **Arithmetic** | `+`, `-`, `*`, `/`, `**` | `fn(:add, a, b)`, `fn(:subtract, a, b)`, etc. |
+| **Comparison** | `>`, `<`, `>=`, `<=`, `==`, `!=` | `fn(:>, a, b)`, `fn(:<, a, b)`, etc. |
+| **Logical** | `&` (AND only) | `fn(:and, a, b)`, `fn(:or, a, b)`, `fn(:not, a)` |
+| **Math** | `abs`, `round`, `ceil`, `floor` | `fn(:abs, x)`, `fn(:round, x)`, etc. |
+| **String** | `.length`, `.upcase`, `.downcase` | `fn(:string_length, s)`, `fn(:upcase, s)`, etc. |
+| **Collection** | `.sum`, `.size`, `.max`, `.min` | `fn(:sum, arr)`, `fn(:size, arr)`, etc. |
+
+### Custom Function Calls
+
+```ruby
+# With Sugar (when available)
+value :clamped_score, input.raw_score.clamp(0, 1600)
+value :formatted_name, input.first_name + " " + input.last_name
+
+# Sugar-Free (always available)
+value :clamped_score, fn(:clamp, input.raw_score, 0, 1600)
+value :formatted_name, fn(:add, fn(:add, input.first_name, " "), input.last_name)
+```
+
+## Cascade Logic
+
+Cascade syntax is the same in both approaches, but conditions use different syntax:
+
+```ruby
+# With Sugar
+value :grade_letter do
+  on :excellent_student, "A+"
+  on :high_scorer, "A"
+  on :above_average, "B"
+  on :needs_improvement, "C"
+  base "F"
+end
+
+# Sugar-Free  
+value :grade_letter do
+  on :excellent_student, "A+"
+  on :high_scorer, "A"
+  on :above_average, "B"
+  on :needs_improvement, "C"
+  base "F"
+end
+```
+
+The difference is in how the traits referenced in cascade conditions are defined (see Trait Declarations above).
+
+## References
+
+### Referencing Other Declarations
+
+```ruby
+# Both syntaxes (same)
+trait :qualified_senior, qualified & (input.age >= 65)
+value :bonus_points, qualified_senior ? 100 : 0
+
+# Explicit reference syntax (both syntaxes)
+trait :qualified_senior, ref(:qualified) & (input.age >= 65)
+value :bonus_points, ref(:qualified_senior) ? 100 : 0
+```
+
+### Input Field References
+
+```ruby
+# Both syntaxes (same)
+input.field_name          # Access input field
+input.field_name.method   # Call method on input field (sugar)
+fn(:method, input.field_name)  # Call method on input field (sugar-free)
+```
+
+## Complete Example Comparison
+
+### With Sugar (Recommended)
+
+```ruby
+module StudentEvaluation
+  extend Kumi::Schema
+
+  schema do
+    input do
+      integer :math_score, domain: 0..800
+      integer :verbal_score, domain: 0..800
+      integer :writing_score, domain: 0..800
+      integer :age, domain: 16..25
+      string :status, domain: %w[active inactive]
+    end
+
+    # Calculated values with sugar
+    value :total_score, input.math_score + input.verbal_score + input.writing_score
+    value :average_score, total_score / 3
+    value :scaled_average, fn(:round, average_score * 1.2, 2)
+
+    # Traits with sugar
+    trait :high_performer, total_score >= 2100
+    trait :math_excellence, input.math_score >= 750
+    trait :eligible_student, (input.age >= 18) & (input.status == "active")
+    trait :scholarship_candidate, high_performer & math_excellence & eligible_student
+
+    # Cascade with sugar-defined traits
+    value :scholarship_amount do
+      on :scholarship_candidate, 10000
+      on :high_performer, 5000
+      on :math_excellence, 2500
+      base 0
+    end
+  end
+end
+```
+
+### Sugar-Free (Explicit)
+
+```ruby
+module StudentEvaluation
+  extend Kumi::Schema
+
+  schema do
+    input do
+      integer :math_score, domain: 0..800
+      integer :verbal_score, domain: 0..800
+      integer :writing_score, domain: 0..800
+      integer :age, domain: 16..25
+      string :status, domain: %w[active inactive]
+    end
+
+    # Calculated values without sugar
+    value :total_score, fn(:add, fn(:add, input.math_score, input.verbal_score), input.writing_score)
+    value :average_score, fn(:divide, total_score, 3)
+    value :scaled_average, fn(:round, fn(:multiply, average_score, 1.2), 2)
+
+    # Traits without sugar
+    trait :high_performer, fn(:>=, total_score, 2100)
+    trait :math_excellence, fn(:>=, input.math_score, 750)
+    trait :eligible_student, fn(:and, fn(:>=, input.age, 18), fn(:==, input.status, "active"))
+    trait :scholarship_candidate, fn(:and, fn(:and, high_performer, math_excellence), eligible_student)
+
+    # Cascade with sugar-free defined traits
+    value :scholarship_amount do
+      on :scholarship_candidate, 10000
+      on :high_performer, 5000
+      on :math_excellence, 2500
+      base 0
+    end
+  end
+end
+```
+
+## When to Use Each Syntax
+
+### Use Sugar Syntax When:
+- ✅ Writing schemas by hand
+- ✅ Readability is important
+- ✅ Working with simple to moderate complexity
+- ✅ You want concise, Ruby-like expressions
+
+### Use Sugar-Free Syntax When:
+- ✅ Generating schemas programmatically
+- ✅ Building dynamic schemas in loops/methods
+- ✅ You need explicit control over function calls
+- ✅ Working with complex nested expressions
+- ✅ Debugging expression evaluation issues
+
+## Syntax Limitations
+
+### Sugar Syntax Limitations:
+- Only supports `&` for logical AND (no `&&` due to Ruby precedence)
+- No logical OR sugar syntax (must use `fn(:or, a, b)`)
+- Limited operator precedence control
+- Some Ruby methods not available as sugar
+
+### Sugar-Free Advantages:
+- Full access to all registered functions
+- Clear operator precedence through explicit nesting
+- Works in all contexts (including programmatic generation)
+- More explicit about what operations are being performed
+
+## Performance Notes
+
+Both syntaxes compile to identical internal representations, so there is **no performance difference** between sugar and sugar-free syntax. Choose based on readability and maintenance needs.

data/examples/deep_schema_compilation_and_evaluation_benchmark.rb

@@ -0,0 +1,106 @@
+# Deep Schema Compilation and Evaluation Benchmark
+#
+# This benchmark measures Kumi's performance with increasingly deep dependency chains
+# to understand how compilation and evaluation times scale with schema depth.
+#
+# What it tests:
+# - Compilation time for schemas with deep dependency chains (50, 100, 150 levels)
+# - Evaluation performance for computing results through long dependency paths
+# - Stack-safe evaluation through iterative dependency resolution
+#
+# Schema structure:
+# - input: single integer seed
+# - values: chain of dependencies v0 = seed, v1 = v0 + 1, v2 = v1 + 2, ..., v_n = v_(n-1) + n
+# - traits: conditional checks at each level (value > threshold)
+# - cascade: final_result depends on first trait that evaluates to true
+#
+# Depth limits: Ruby stack overflow occurs around 200-300 levels depending on system,
+# so we test with conservative depths (50, 100, 150) to ensure reliability.
+#
+# Usage: bundle exec ruby examples/deep_schema_compilation_and_evaluation_benchmark.rb
+require "benchmark"
+require "benchmark/ips"
+require_relative "../lib/kumi"
+
+# ------------------------------------------------------------------
+# 1. Helper that builds a deep dependency chain schema
+# ------------------------------------------------------------------
+def build_deep_schema(depth)
+  Class.new do
+    extend Kumi::Schema
+
+    schema do
+      input { integer :seed }
+
+      # Build dependency chain: v0 = seed, v1 = v0 + 1, v2 = v1 + 2, etc.
+      value :v0, input.seed
+      
+      (1...depth).each do |i|
+        value :"v#{i}", fn(:add, ref(:"v#{i-1}"), i)
+      end
+
+      # Build traits that check if values exceed thresholds
+      # Use varying thresholds to create realistic evaluation scenarios
+      (0...depth).each do |i|
+        threshold = i * (i + 1) / 2 + 1000  # Quadratic growth to ensure variety
+        trait :"threshold_#{i}", fn(:>, ref(:"v#{i}"), threshold)
+      end
+
+      # Final cascade that finds first trait that's true
+      value :final_result do
+        (0...depth).each do |i|
+          on :"threshold_#{i}", fn(:multiply, ref(:"v#{i}"), 2)
+        end
+        base ref(:"v#{depth-1}")  # Default to final value
+      end
+    end
+  end
+end
+
+# Conservative depths to avoid Ruby stack overflow
+# Ruby stack depth limit is around 1000-2000 frames depending on the system
+# Keep depths well below this limit for reliable operation
+DEPTHS = [50, 100, 150, 200]
+
+# ------------------------------------------------------------------
+# 2. Measure compilation once per depth
+# ------------------------------------------------------------------
+compile_times = {}
+schemas       = {}
+
+DEPTHS.each do |d|
+  puts "\n--- Building #{d}-deep schema ---"
+  t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  schemas[d] = build_deep_schema(d)
+  compile_times[d] = Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0
+end
+
+puts "=== compilation times ==="
+compile_times.each do |d, t|
+  puts format("compile %3d-deep: %6.1f ms", d, t * 1_000)
+end
+puts
+
+# ------------------------------------------------------------------
+# 3. Pure evaluation benchmark – no compilation inside the loop
+# ------------------------------------------------------------------
+Benchmark.ips do |x|
+  schemas.each do |d, schema|
+    runner = schema.from(seed: 0)          # memoised runner
+    x.report("eval #{d}-deep") { runner[:final_result] }
+  end
+  x.compare!
+end
+# Warming up --------------------------------------
+#         eval 50-deep   222.000 i/100ms
+#        eval 100-deep    57.000 i/100ms
+#        eval 150-deep    26.000 i/100ms
+# Calculating -------------------------------------
+#         eval 50-deep      2.166k (± 1.9%) i/s  (461.70 μs/i) -     10.878k in   5.024320s
+#        eval 100-deep    561.698 (± 1.4%) i/s    (1.78 ms/i) -      2.850k in   5.075057s
+#        eval 150-deep    253.732 (± 0.8%) i/s    (3.94 ms/i) -      1.274k in   5.021499s
+
+# Comparison:
+#         eval 50-deep:     2165.9 i/s
+#        eval 100-deep:      561.7 i/s - 3.86x  slower
+#        eval 150-deep:      253.7 i/s - 8.54x  slower