kumi 0.0.4 → 0.0.6

data/README.md

@@ -3,287 +3,365 @@
 [![CI](https://github.com/amuta/kumi/workflows/CI/badge.svg)](https://github.com/amuta/kumi/actions)
 [![Gem Version](https://badge.fury.io/rb/kumi.svg)](https://badge.fury.io/rb/kumi)
 
-Kumi is a declarative rule‑and‑calculation DSL for Ruby that turns scattered business logic into a statically‑checked dependency graph.
+Kumi is a Declarative logic framework with static analysis for Ruby.
 
-Every input, trait, and formula is compiled into a typed AST node, so the entire graph is explicit and introspectable.
+It is well-suited for scenarios with complex, interdependent calculations, enforcing validation and consistency across your business rules while maintaining performance.
 
-Note: The examples here are small for the sake of readability. I would not recommend using this gem unless you need to keep track of 100+ conditions/variables.
 
 
-## How to get started
+## What can you build?
 
-Install Kumi and try running the examples below or explore the `./examples` directory of this repository.
-```
-gem install kumi
-```
-
-## Example
+Calculate U.S. federal taxes:
 
-**Instead of scattered logic:**
 ```ruby
-def calculate_loan_approval(credit_score, income, debt_ratio)
-  good_credit = credit_score >= 700
-  sufficient_income = income >= 50_000  
-  low_debt = debt_ratio <= 0.3
-  
-  if good_credit && sufficient_income && low_debt
-    { approved: true, rate: 3.5 }
-  else
-    { approved: false, rate: nil }
-  end
-end
-```
-
-**You can write:**
-```ruby
-module LoanApproval
+module FederalTax2024
   extend Kumi::Schema
-
+  
   schema do
     input do
-      integer :credit_score
-      float :income
-      float :debt_to_income_ratio
+      float  :income
+      string :filing_status, domain: %w[single married_joint]
     end
-
-    trait :good_credit, input.credit_score >= 700
-    trait :sufficient_income, input.income >= 50_000
-    trait :low_debt, input.debt_to_income_ratio <= 0.3
-    trait :approved, good_credit & sufficient_income & low_debt
     
-    value :interest_rate do
-      on :approved, 3.5
-      base 0.0
+    # Standard deduction by filing status
+    trait :single,  input.filing_status == "single"
+    trait :married, input.filing_status == "married_joint"
+    
+    value :std_deduction do
+      on single,  14_600
+      on married, 29_200
+      base        21_900  # head_of_household
+    end
+    
+    value :taxable_income, fn(:max, [input.income - std_deduction, 0])
+    
+    # Federal tax brackets
+    value :fed_breaks do
+      on single,  [11_600, 47_150, 100_525, 191_950, 243_725, 609_350, Float::INFINITY]
+      on married, [23_200, 94_300, 201_050, 383_900, 487_450, 731_200, Float::INFINITY]
     end
+    
+    value :fed_rates, [0.10, 0.12, 0.22, 0.24, 0.32, 0.35, 0.37]
+    value :fed_calc,  fn(:piecewise_sum, taxable_income, fed_breaks, fed_rates)
+    value :fed_tax,   fed_calc[0]
+    
+    # FICA taxes
+    value :ss_tax, fn(:min, [input.income, 168_600]) * 0.062
+    value :medicare_tax, input.income * 0.0145
+    
+    value :total_tax, fed_tax + ss_tax + medicare_tax
+    value :after_tax, input.income - total_tax
   end
 end
 
-runner = LoanApproval.from(credit_score: 750, income: 60_000, debt_to_income_ratio: 0.25)
-puts runner[:approved]       # => true
-puts runner[:interest_rate]  # => 3.5
+# Use it
+result = FederalTax2024.from(income: 100_000, filing_status: "single")
+result[:total_tax]   # => 21,491.00
+result[:after_tax]   # => 78,509.00
 ```
 
-This gets you:
-- Static analysis catches impossible logic combinations at compile time
-- Automatic dependency tracking prevents circular references  
-- Type safety with domain constraints (age: 0..150, status: %w[active inactive])
-- Microsecond performance not much different than optimized pure ruby
-- Introspectable - see exactly how any value was computed
+Real tax calculation with brackets, deductions, and FICA caps. Validation happens during schema definition.
 
-## Static Analysis & Safety
+Kumi is well-suited for scenarios with complex, interdependent calculations, enforcing validation and consistency across your business rules while maintaining performance.
 
-Kumi analyzes your rules to catch logical impossibilities:
+## Installation
 
-```ruby
-module ImpossibleLogic
-  extend Kumi::Schema
+```bash
+# Requires Ruby 3.0+
+# No external dependencies
+gem install kumi
+```
 
-  schema do
-    input {}  # No inputs needed
+## Core Features
 
-    value :x, 100
-    trait :x_less_than_100, x < 100        # false: 100 < 100
-    
-    value :y, x * 10                       # 1000  
-    trait :y_greater_than_1000, y > 1000   # false: 1000 > 1000
+<details>
+<summary><strong>📊 Schema Primitives</strong> - Four building blocks for business logic</summary>
 
-    value :result do
-      # This is impossible
-      on :x_less_than_100 & :y_greater_than_1000, "Impossible!"
-      base "Default"
-    end
-  end
-end
+### Schema Primitives
 
-# Kumi::Errors::SemanticError: conjunction `x_less_than_100 AND y_greater_than_1000` is impossible
-```
+Kumi schemas are built from four primitives:
 
-Cycle detection:
+**Inputs** define the data flowing into your schema with built-in validation:
 ```ruby
-module CircularDependency
-  extend Kumi::Schema
+input do
+  float :price, domain: 0..1000.0      # Validates range
+  integer :quantity, domain: 1..10000   # Validates range
+  string :tier, domain: %w[standard premium]  # Validates inclusion
+end
+```
 
-  schema do
-    input { float :base }
+**Values** are computed attributes that automatically memoize their results
+```ruby
+value :subtotal, input.price * input.quantity
+value :tax_rate, 0.08
+value :tax_amount, subtotal * tax_rate
+```
 
-    # These create a circular dependency
-    value :monthly_rate, yearly_rate / 12
-    value :yearly_rate, monthly_rate * 12
-  end
+**Traits** are boolean conditions that enable branching logic:
+```ruby
+trait :bulk_order, input.quantity >= 100
+trait :premium_customer, input.tier == "premium"
+
+value :discount do
+  on bulk_order, premium_customer, 0.25  # 25% for bulk premium orders
+  on bulk_order, 0.15                     # 15% for bulk orders
+  on premium_customer, 0.10               # 10% for premium customers
+  base 0.0                                # No discount otherwise
 end
+```
 
-# Kumi::Errors::SemanticError: cycle detected involving: monthly_rate → yearly_rate → monthly_rate
+**Functions** provide computational building blocks:
+
+```ruby
+value :final_price, [subtotal - discount_amount, 0].max
+value :monthly_payment, fn(:pmt, rate: 0.05/12, nper: 36, pv: -loan_amount)
 ```
+Note: You can find a list all core functions in [docs/FUNCTIONS.md](docs/FUNCTIONS.md)
 
-## Performance
+These primitives are statically analyzed during schema definition to catch logical errors before runtime.
 
-Kumi has microsecond evaluation times through automatic memoization:
+</details>
 
-### Deep Dependency Chains
-```
-=== Evaluation Performance (with Memoization) ===
-eval  50-deep:  817,497 i/s  (1.22 μs/i)
-eval 100-deep:  509,567 i/s  (1.96 μs/i) 
-eval 150-deep:  376,429 i/s  (2.66 μs/i)
-eval 200-deep:  282,243 i/s  (3.54 μs/i)
-```
+<details>
+<summary><strong>🔍 Static Analysis</strong> - Catch business logic errors at definition time</summary>
 
-### Wide Complex Schemas  
-```
-=== Evaluation Performance (with Memoization) ===
-eval  1,000-wide:  127,652 i/s  (7.83 μs/i)
-eval  5,000-wide:   26,604 i/s  (37.59 μs/i) 
-eval 10,000-wide:   13,670 i/s  (73.15 μs/i)
-```
+### Static Analysis
+
+Kumi catches business logic errors that cause runtime failures or silent bugs:
 
-Here's how the memoization works:
 ```ruby
-module ProductPricing
+module InsurancePolicyPricer
   extend Kumi::Schema
   
   schema do
     input do
-      float :base_price
-      float :tax_rate
-      integer :quantity
+      integer :age, domain: 18..80
+      string :risk_category, domain: %w[low medium high]
+      float :coverage_amount, domain: 50_000..2_000_000
+      integer :years_experience, domain: 0..50
+      boolean :has_claims
+    end
+    
+    # Risk assessment with subtle interdependencies
+    trait :young_driver, input.age < 25
+    trait :experienced, input.years_experience >= 5
+    trait :high_risk, input.risk_category == "high"
+    trait :senior_driver, input.age >= 65
+    
+    # Base premium calculation
+    value :base_premium, input.coverage_amount * 0.02
+    
+    # Experience adjustment with subtle circular reference
+    value :experience_factor do
+      on experienced & young_driver, experience_discount * 0.8  # ❌ Uses experience_discount before it's defined
+      on experienced, 0.85
+      on young_driver, 1.25
+      base 1.0
+    end
+    
+    # Risk multipliers that create impossible combinations
+    value :risk_multiplier do
+      on high_risk & experienced, 1.5    # High risk but experienced
+      on high_risk, 2.0                  # Just high risk
+      on low_risk & young_driver, 0.9    # ❌ low_risk is undefined (typo for input.risk_category)
+      base 1.0
     end
     
-    value :unit_price_with_tax, input.base_price * (1 + input.tax_rate)
-    value :total_before_discount, unit_price_with_tax * input.quantity
-    value :bulk_discount, input.quantity >= 10 ? 0.1 : 0.0
-    value :final_total, total_before_discount * (1 - bulk_discount)
+    # Claims history impact
+    trait :claims_free, fn(:not, input.has_claims)
+    trait :perfect_record, claims_free & experienced & fn(:not, young_driver)
+    
+    # Discount calculation with type error
+    value :experience_discount do
+      on perfect_record, input.years_experience + "%" # ❌ String concatenation with integer
+      on claims_free, 0.95
+      base 1.0
+    end
+    
+    # Premium calculation chain
+    value :adjusted_premium, base_premium * experience_factor * risk_multiplier
+    
+    # Age-based impossible logic
+    trait :mature_professional, senior_driver & experienced & young_driver  # ❌ Can't be senior AND young
+    
+    # Final premium with self-referencing cascade
+    value :final_premium do
+      on mature_professional, adjusted_premium * 0.8
+      on senior_driver, adjusted_premium * senior_adjustment  # ❌ senior_adjustment undefined
+      base final_premium * 1.1  # ❌ Self-reference in base case
+    end
+    
+    # Monthly payment calculation with function arity error
+    value :monthly_payment, fn(:divide, final_premium)  # ❌ divide needs 2 arguments, got 1
   end
 end
 
-runner = ProductPricing.from(base_price: 100.0, tax_rate: 0.08, quantity: 15)
-
-# First access: computes and caches all intermediate values
-puts runner[:final_total]           # => 1458.0 (computed + cached)
-
-# Subsequent accesses: pure cache lookups (microsecond performance)
-puts runner[:unit_price_with_tax]   # => 108.0 (from cache)
-puts runner[:bulk_discount]         # => 0.1 (from cache) 
-puts runner[:final_total]           # => 1458.0 (from cache)
+# Static analysis catches these errors:
+# ❌ Circular reference: experience_factor → experience_discount → experience_factor
+# ❌ Undefined reference: low_risk (should be input.risk_category == "low")
+# ❌ Type mismatch: integer + string in experience_discount
+# ❌ Impossible conjunction: senior_driver & young_driver
+# ❌ Undefined reference: senior_adjustment
+# ❌ Self-reference cycle: final_premium references itself in base case
+# ❌ Function arity error: divide expects 2 arguments, got 1
 ```
 
-Architecture notes:
-- Compile-once, evaluate-many: Schema compilation happens once, evaluations are pure computation
-- `EvaluationWrapper` caches computed values automatically for subsequent access
-- Stack-safe algorithms: Iterative cycle detection and dependency resolution prevent stack overflow
-- Type-safe execution: No runtime type checking overhead after compilation
-
-## DSL Features
+**Bounded Recursion**: Kumi allows mutual recursion when cascade conditions are mutually exclusive:
 
-### Domain Constraints
 ```ruby
-module UserProfile
-  extend Kumi::Schema
-
-  schema do
-    input do
-      integer :age, domain: 0..150
-      string :status, domain: %w[active inactive suspended]
-      float :score, domain: 0.0..100.0
-    end
-
-    trait :adult, input.age >= 18
-    trait :active_user, input.status == "active"
-  end
+trait :is_forward, input.operation == "forward"
+trait :is_reverse, input.operation == "reverse"
+
+# Safe mutual recursion - conditions are mutually exclusive
+value :forward_processor do
+  on is_forward, input.value * 2        # Direct calculation
+  on is_reverse, reverse_processor + 10  # Delegates to reverse (safe)
+  base "invalid operation"
 end
 
-# Valid data works fine
-UserProfile.from(age: 25, status: "active", score: 85.5)
+value :reverse_processor do
+  on is_forward, forward_processor - 5   # Delegates to forward (safe) 
+  on is_reverse, input.value / 2         # Direct calculation
+  base "invalid operation"
+end
 
-# Invalid data raises detailed errors
-UserProfile.from(age: 200, status: "invalid", score: -10)
-# => Kumi::Errors::DomainViolationError: Domain constraint violations...
+# Usage examples:
+# operation="forward", value=10  => forward: 20, reverse: 15
+# operation="reverse", value=10  => forward: 15, reverse: 5  
+# operation="unknown", value=10  => both: "invalid operation"
 ```
 
-### Cascade Logic
-```ruby
-module ShippingCost
-  extend Kumi::Schema
+This compiles because `operation` can only be "forward" or "reverse", never both. Each recursion executes one step before hitting a direct calculation.
 
-  schema do
-    input do
-      float :order_total
-      string :membership_level
-    end
+</details>
 
-    trait :premium_member, input.membership_level == "premium"
-    trait :large_order, input.order_total >= 100
+<details>
+<summary><strong>🔍 Array Broadcasting</strong> - Automatic vectorization over array fields</summary>
 
-    value :shipping_cost do
-      on :premium_member, 0.0
-      on :large_order, 5.0
-      base 15.0
+### Array Broadcasting
+
+Kumi broadcasts operations over array fields for element-wise computation:
+
+```ruby
+schema do
+  input do
+    array :line_items do
+      float   :price
+      integer :quantity
+      string  :category
     end
+    float :tax_rate
   end
-end
 
-runner = ShippingCost.from(order_total: 75, membership_level: "standard")
-puts runner[:shipping_cost]  # => 15.0
+  # 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")
+  
+  # Aggregation operations - consume arrays to produce scalars
+  value :total_subtotal, fn(:sum, subtotals)
+  value :item_count, fn(:size, input.line_items)
+end
 ```
 
-### Functions
-```ruby
-module Statistics
-  extend Kumi::Schema
+**Dimension Mismatch Detection**: Operations across different arrays generate error messages:
 
-  schema do
-    input do
-      array :scores, elem: { type: :float }
+```ruby
+schema do
+  input do
+    array :items do
+      string :name
+    end
+    array :logs do  
+      string :user_name
     end
-
-    value :total, fn(:sum, input.scores)
-    value :count, fn(:size, input.scores)
-    value :average, total / count
-    value :max_score, fn(:max, input.scores)
   end
+
+  # This generates an error
+  trait :same_name, input.items.name == input.logs.user_name
 end
 
-runner = Statistics.from(scores: [85.5, 92.0, 78.5, 96.0])
-puts runner[:average]    # => 88.0
-puts runner[:max_score]  # => 96.0
+# 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.
 ```
 
-## Introspection
+</details>
+
+<details>
+<summary><strong>💾 Automatic Memoization</strong> - Each value computed exactly once</summary>
+
+### Automatic Memoization
 
-You can see exactly how any value was computed:
+Each value is computed exactly once:
 
 ```ruby
-module TaxCalculator
-  extend Kumi::Schema
+runner = FederalTax2024.from(income: 250_000, filing_status: "married_joint")
 
-  schema do
-    input do
-      float :income
-      float :tax_rate
-      float :deductions
-    end
+# First access computes full dependency chain
+runner[:total_tax]     # => 53,155.20
 
-    value :taxable_income, input.income - input.deductions
-    value :tax_amount, taxable_income * input.tax_rate
-  end
-end
+# Subsequent access uses cached values
+runner[:fed_tax]       # => 39,077.00 (cached)
+runner[:after_tax]     # => 196,844.80 (cached)
+```
 
-inputs = { income: 100_000, tax_rate: 0.25, deductions: 12_000 }
+</details>
 
-puts Kumi::Explain.call(TaxCalculator, :taxable_income, inputs: inputs)
-# => taxable_income = input.income - deductions = (input.income = 100 000) - (deductions = 12 000) => 88 000
+<details>
+<summary><strong>🔍 Introspection</strong> - See exactly how values are calculated</summary>
 
-puts Kumi::Explain.call(TaxCalculator, :tax_amount, inputs: inputs)  
-# => tax_amount = taxable_income × input.tax_rate = (taxable_income = 88 000) × (input.tax_rate = 0.25) => 22 000
-```
+### Introspection
 
-## Try It Yourself
+Show how values are calculated:
 
-Run the performance benchmarks:
-```bash
-bundle exec ruby examples/wide_schema_compilation_and_evaluation_benchmark.rb
-bundle exec ruby examples/deep_schema_compilation_and_evaluation_benchmark.rb
+```ruby
+Kumi::Explain.call(FederalTax2024, :fed_tax, inputs: {income: 100_000, filing_status: "single"})
+# => fed_tax = fed_calc[0]
+#    = (fed_calc = piecewise_sum(taxable_income, fed_breaks, fed_rates)
+#       = piecewise_sum(85,400, [11,600, 47,150, ...], [0.10, 0.12, ...])
+#       = [15,099.50, 0.22])
+#    = 15,099.50
 ```
 
-## DSL Syntax Reference
+</details>
+
+## Usage
+
+**Suitable for:**
+- Complex interdependent business rules
+- Tax calculation engines
+- Insurance premium calculators
+- Loan amortization schedules
+- Commission structures with complex tiers
+- Pricing engines with multiple discount rules
+
+**Not suitable for:**
+- Simple conditional statements
+- Sequential procedural workflows  
+- Rules that change during execution
+- High-frequency real-time processing
+
+## Performance
+
+Benchmarks on Linux with Ruby 3.3.8 on a Dell Latitude 7450:
+- 50-deep dependency chain: **740,000/sec** (analysis <50ms)
+- 1,000 attributes:         **131,000/sec** (analysis <50ms)
+- 10,000 attributes:        **14,200/sec**  (analysis ~300ms)
+
+## Learn More
+
+- [DSL Syntax Reference](docs/SYNTAX.md)
+- [Examples](examples/)/
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/amuta/kumi.
+
+## License
 
-See [`documents/SYNTAX.md`](documents/SYNTAX.md) for complete syntax documentation with sugar vs sugar-free examples.
+MIT License. See [LICENSE](LICENSE).