kumi 0.0.4 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 243e6f2e2f7f65919f41fae1eddf877796e6221674e41dc5d32a36c708efab03
-  data.tar.gz: 8649def0a1299dd416d00480daa9fb0dfe3b6e418c4ea6c1ad869c873ad3eedf
+  metadata.gz: 5d4a3efa20727ebc89e39753f240bb6ed8fc3621b32771ea3b6d9096bdc21af5
+  data.tar.gz: 4c0a147c66d2b2ece9bec196b665d7b5fe613bb021caa5ec3efc00f0e0e6ed94
 SHA512:
-  metadata.gz: e677d95d1ef34f8144b1f829259ad716e8f3822ab216957cf34a0058b4f7651843232202dc485a62e4c44077761a91b4db419963b649fae4a429042bf49be410
-  data.tar.gz: 3e7795238333d362f35c71b9478b01f4ff396110dc517a320dc304288a1ab8deac0a3af8b99c3d8f87cfd47a9a91f1bbd46509eb0055db4faa042b9b6ca14bd9
+  metadata.gz: 4e029e73067c2403290e1af7d9c841a1f8fad6782636275ec24b0626e3086684765e3010c727f839febd4238a61fe3723388ab899e4dece18701a720608a39df
+  data.tar.gz: e9a83993e264eca2a67821a9bc6d3f7bd59815c9c593fcd119fbbaed93fb92c345211023366aab076a35ef248b3580f84531aa52e1726463345e77e32c810ecb

data/CLAUDE.md

@@ -27,6 +27,19 @@ Kumi is a declarative decision-modeling compiler for Ruby that transforms comple
 - `gem build kumi.gemspec` - Build the gem
 - `gem install ./kumi-*.gem` - Install locally built gem
 
+### Kumi CLI
+- `./bin/kumi -i` - Start interactive REPL mode for rapid schema testing
+- `./bin/kumi -f schema.rb -d data.json` - Execute schema file with input data
+- `./bin/kumi -f schema.rb -k key1,key2` - Extract specific keys from schema
+- `./bin/kumi -f schema.rb -e key_name` - Explain how a key is computed
+- `./bin/kumi -f schema.rb -d data.json -o json` - Output results in JSON format
+
+**CLI Features**:
+- Interactive REPL with schema loading, data manipulation, and live evaluation
+- File-based schema execution with JSON/YAML input data support
+- Selective key extraction and explain functionality for debugging
+- Multiple output formats (pretty, JSON, YAML) for integration
+
 ## Architecture Overview
 
 ### Core Components
@@ -91,6 +104,58 @@ Kumi is a declarative decision-modeling compiler for Ruby that transforms comple
 - `domain/enum_analyzer.rb` - Enumeration domain analysis and validation
 - `domain/violation_formatter.rb` - Formats domain violation error messages
 
+## DSL Syntax Requirements
+
+### Critical Syntax Rules
+
+**Module Definition Structure** (REQUIRED for CLI):
+```ruby
+# CORRECT - CLI can find and load this
+module SchemaName
+  extend Kumi::Schema
+  
+  schema do
+    # schema definition here
+  end
+end
+
+# INCORRECT - CLI cannot load standalone schemas
+schema do  # This won't work with CLI
+  # schema definition
+end
+```
+
+**Function Call Syntax**:
+- **Symbol style**: `fn(:function_name, arg1, arg2)` - Always works, explicit
+- **Method style**: `fn.function_name(arg1, arg2)` - Also works, more readable
+- **Incorrect**: `fn()` - Empty function calls cause parse errors
+- **Incorrect**: `fn.function_name()` - Empty method calls cause parse errors
+
+**Arithmetic Operations**:
+- **Sugar Syntax**: `input.field1 + input.field2` - Works for input fields and value references
+- **Function Syntax**: `fn(:add, input.field1, input.field2)` - Always works, more explicit
+- **Mixed**: Use sugar for simple operations, functions for complex ones
+
+**Cascade Condition Syntax**:
+```ruby
+# CORRECT - use symbols for trait references in cascades
+value :status do
+  on trait_name, "Result"
+  base "Default"
+end
+
+# INCORRECT - bare identifiers don't work in cascade conditions
+value :status do
+  on trait_name, "Result"  # This will fail
+  base "Default"
+end
+```
+
+**UnsatDetector Considerations**:
+- Cascades with mutually exclusive conditions are valid (e.g., `amount < 100` vs `amount >= 100`)
+- Values that depend on such cascades are also valid (fixed in recent update)
+- Use clear, non-contradictory trait names to avoid confusion
+
 ### Key Patterns
 
 **DSL Structure**:
@@ -120,8 +185,8 @@ end
 In cascade expressions (`value :name do ... end`), trait references use **symbols**, not bare identifiers:
 ```ruby
 value :status do
-  on :adult, "Adult Status"      # ✅ Correct - use :trait_name symbol
-  on :verified, "Verified User"
+  on adult, "Adult Status"      # ✅ Correct - use trait_name symbol
+  on verified, "Verified User"
   base "Unverified"
 end
 
@@ -199,6 +264,48 @@ The `examples/` directory contains comprehensive examples showing Kumi usage pat
 10. `documents/DSL.md` - Concise DSL syntax reference
 11. `documents/AST.md` - AST node types and structure reference
 12. `documents/SYNTAX.md` - Comprehensive sugar vs sugar-free syntax comparison with examples
+13. `lib/kumi/cli.rb` - CLI implementation with REPL and file execution
+14. `examples/simple_tax_schema.rb` - CLI-compatible schema example
+
+## CLI Usage and Best Practices
+
+### Schema File Requirements
+- **Must use module structure**: `module SchemaName; extend Kumi::Schema; schema do ... end; end`
+- **Must have proper require**: `require_relative "../lib/kumi"` at the top
+- **Must have input block**: Even empty `input {}` blocks are required
+- **Avoid inline definitions**: Don't define schemas directly in methods or blocks
+
+### CLI Development Workflow
+1. **Start with REPL**: Use `./bin/kumi -i` for rapid prototyping and testing
+2. **Test with files**: Create `.rb` schema files and `.json/.yaml` data files
+3. **Iterate quickly**: Use `-k key1,key2` to focus on specific outputs
+4. **Debug with explain**: Use `-e key_name` to understand computation flow
+5. **Validate with different data**: Test edge cases with varied input data
+
+### Common CLI Patterns
+```bash
+# Interactive development
+./bin/kumi -i
+kumi> schema examples/my_schema.rb
+kumi> data test_data.json
+kumi> get result
+
+# File-based execution
+./bin/kumi -f examples/tax_schema.rb -d examples/tax_data.json -k total_tax,effective_rate
+
+# Debugging computations
+./bin/kumi -f examples/complex_schema.rb -d examples/data.json -e complex_calculation
+
+# Output formats for integration
+./bin/kumi -f schema.rb -d data.json -k results -o json | jq '.results'
+```
+
+### Troubleshooting Schema Issues
+- **Parse Errors**: Check function syntax (avoid empty `fn()` calls)
+- **Module Not Found**: Ensure proper module structure and naming
+- **UnsatDetector Errors**: Review trait logic for contradictions
+- **Type Errors**: Check input block type declarations match usage
+- **Runtime Errors**: Use explain to trace computation dependencies
 
 ## Input Block System Details
 

data/README.md

@@ -3,287 +3,243 @@
 [![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 computational rules engine for Ruby (plus static validation, dependency tracking, and more)
 
-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 in 30 lines of validated, readable code:
 
-**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
+Is is well-suited for scenarios with complex, interdependent calculations, enforcing ...
 
-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
+Here's a concise "Key Concepts" section for your README:
 
-    value :result do
-      # This is impossible
-      on :x_less_than_100 & :y_greater_than_1000, "Impossible!"
-      base "Default"
-    end
-  end
-end
+## Key Concepts
 
-# Kumi::Errors::SemanticError: conjunction `x_less_than_100 AND y_greater_than_1000` is impossible
-```
+Kumi schemas are built from four simple primitives that compose into powerful business logic:
 
-Cycle detection:
+**Inputs** define the data flowing into your schema with built-in validation:
 ```ruby
-module CircularDependency
-  extend Kumi::Schema
-
-  schema do
-    input { float :base }
-
-    # These create a circular dependency
-    value :monthly_rate, yearly_rate / 12
-    value :yearly_rate, monthly_rate * 12
-  end
+input do
+  float :price, domain: 0..1000.0      # Validates range
+  string :category, domain: %w[standard premium]  # Validates inclusion
 end
-
-# Kumi::Errors::SemanticError: cycle detected involving: monthly_rate → yearly_rate → monthly_rate
 ```
 
-## Performance
-
-Kumi has microsecond evaluation times through automatic memoization:
-
-### 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)
-```
-
-### 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)
+**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
 ```
 
-Here's how the memoization works:
+**Traits** are boolean conditions that enable branching logic:
 ```ruby
-module ProductPricing
-  extend Kumi::Schema
-  
-  schema do
-    input do
-      float :base_price
-      float :tax_rate
-      integer :quantity
-    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)
-  end
+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
-
-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)
 ```
 
-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
+**Functions** provide computational building blocks:
 
-## DSL Features
-
-### Domain Constraints
 ```ruby
-module UserProfile
-  extend Kumi::Schema
+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 [FUNCTIONS.md](documents/FUNCTIONS.md)
 
-  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
-end
+These primitives are statically analyzed during schema definition, catching logical errors before runtime and ensuring your business rules are internally consistent.
 
-# Valid data works fine
-UserProfile.from(age: 25, status: "active", score: 85.5)
 
-# Invalid data raises detailed errors
-UserProfile.from(age: 200, status: "invalid", score: -10)
-# => Kumi::Errors::DomainViolationError: Domain constraint violations...
-```
+### Static Analysis
+
+Kumi catches real business logic errors during schema definition:
 
-### Cascade Logic
 ```ruby
-module ShippingCost
+module CommissionCalculator
   extend Kumi::Schema
-
+  
   schema do
     input do
-      float :order_total
-      string :membership_level
+      float :sales_amount, domain: 0..Float::INFINITY
+      integer :years_experience, domain: 0..50
+      string :region, domain: %w[east west north south]
     end
-
-    trait :premium_member, input.membership_level == "premium"
-    trait :large_order, input.order_total >= 100
-
-    value :shipping_cost do
-      on :premium_member, 0.0
-      on :large_order, 5.0
-      base 15.0
+    
+    # Commission tiers based on experience
+    trait :junior, input.years_experience < 2
+    trait :senior, input.years_experience >= 5
+    trait :veteran, input.years_experience >= 10
+    
+    # Base commission rates
+    value :base_rate do
+      on veteran, 0.08
+      on senior, 0.06
+      on junior, 0.04
+      base 0.05
+    end
+    
+    # Regional multipliers
+    value :regional_bonus do
+      on input.region == "west", 1.2  # West coast bonus
+      on input.region == "east", 1.1  # East coast bonus
+      base 1.0
+    end
+    
+    # Problem: Veteran bonus conflicts with senior cap
+    value :experience_bonus do
+      on veteran, 2.0      # Veterans get 2x bonus
+      on senior, 1.5       # Seniors get 1.5x bonus  
+      base 1.0
+    end
+    
+    value :total_rate, base_rate * regional_bonus * experience_bonus
+    
+    # Business rule error: Veterans (10+ years) are also seniors (5+ years)
+    # This creates impossible logic in commission caps
+    trait :capped_senior, :senior & (total_rate <= 0.10)  # Senior cap
+    trait :uncapped_veteran, :veteran & (total_rate > 0.10)  # Veteran override
+    
+    value :final_commission do
+      on capped_senior & uncapped_veteran, "Impossible!"  # Can't be both
+      on uncapped_veteran, input.sales_amount * total_rate
+      on capped_senior, input.sales_amount * 0.10
+      base input.sales_amount * total_rate
     end
   end
 end
 
-runner = ShippingCost.from(order_total: 75, membership_level: "standard")
-puts runner[:shipping_cost]  # => 15.0
+# => conjunction `capped_senior AND uncapped_veteran` is impossible
 ```
 
-### Functions
-```ruby
-module Statistics
-  extend Kumi::Schema
+### Automatic Memoization
 
-  schema do
-    input do
-      array :scores, elem: { type: :float }
-    end
+Each value is computed exactly once:
 
-    value :total, fn(:sum, input.scores)
-    value :count, fn(:size, input.scores)
-    value :average, total / count
-    value :max_score, fn(:max, input.scores)
-  end
-end
+```ruby
+runner = FederalTax2024.from(income: 250_000, filing_status: "married_joint")
+
+# First access computes full dependency chain
+runner[:total_tax]     # => 52,937.50
 
-runner = Statistics.from(scores: [85.5, 92.0, 78.5, 96.0])
-puts runner[:average]    # => 88.0
-puts runner[:max_score]  # => 96.0
+# Subsequent access uses cached values
+runner[:fed_tax]       # => 37,437.50 (cached)
+runner[:after_tax]     # => 197,062.50 (cached)
 ```
 
-## Introspection
+### Introspection
 
-You can see exactly how any value was computed:
+See exactly how any value was calculated:
 
 ```ruby
-module TaxCalculator
-  extend Kumi::Schema
+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
+```
 
-  schema do
-    input do
-      float :income
-      float :tax_rate
-      float :deductions
-    end
+## Suggested Use Cases
 
-    value :taxable_income, input.income - input.deductions
-    value :tax_amount, taxable_income * input.tax_rate
-  end
-end
+- Complex interdependent business rules
+- Tax calculation engines (as demonstrated)
+- Insurance premium calculators
+- Loan amortization schedules
+- Commission structures with complex tiers
+- Pricing engines with multiple discount rules
 
-inputs = { income: 100_000, tax_rate: 0.25, deductions: 12_000 }
+**Not suitable for:**
+- Simple conditional statements
+- Sequential procedural workflows  
+- Rules that change during execution
+- High-frequency real-time processing
 
-puts Kumi::Explain.call(TaxCalculator, :taxable_income, inputs: inputs)
-# => taxable_income = input.income - deductions = (input.income = 100 000) - (deductions = 12 000) => 88 000
+## Performance
 
-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
-```
+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)
 
-## Try It Yourself
+## Learn More
 
-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
-```
+- [DSL Syntax Reference](documents/SYNTAX.md)
+- [Examples](examples/)/
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/amuta/kumi.
 
-## DSL Syntax Reference
+## License
 
-See [`documents/SYNTAX.md`](documents/SYNTAX.md) for complete syntax documentation with sugar vs sugar-free examples.
+MIT License. See [LICENSE](LICENSE).

data/documents/DSL.md

@@ -109,13 +109,13 @@ For conditional logic, a `value` takes a block to create a **cascade**. Cascades
 ```ruby
 value :access_level do
   # `on` implies AND: user must be :premium AND :verified.
-  on :premium, :verified, "Full Access"
+  on premium,verified, "Full Access"
 
   # `on_any` implies OR: user can be :staff OR :admin.
-  on_any :staff, :admin, "Elevated Access"
+  on_any staff,admin, "Elevated Access"
 
   # `on_none` implies NOT (A OR B): user is neither :blocked NOR :suspended.
-  on_none :blocked, :suspended, "Limited Access"
+  on_none blocked,suspended, "Limited Access"
 
   # `base` is the default if no other conditions match.
   base "No Access"