kumi 0.0.15 → 0.0.17

data/config/functions.yaml

@@ -1,352 +0,0 @@
-# ==================== CORE - SCALAR (elementwise) ====================
-
-- name: core.add
-  domain: core
-  opset: 1
-  class: scalar
-  summary: Numeric addition with broadcasting
-  signature: ["(),()->()", "(i),(i)->(i)", "(i,j),(i,j)->(i,j)"]
-  type_vars: {T: Numeric, U: Numeric}
-  dtypes: {result: "promote(T,U)", casting: "same_kind"}
-  null_policy: propagate
-  algebra: {associative: true, commutative: true, identity: 0}
-  vectorization: {mask_aware: true}
-  kernels: 
-    - backend: ruby
-      impl: kumi_add
-      priority: 10
-
-- name: core.sub
-  domain: core
-  opset: 1
-  class: scalar
-  signature: ["(),()->()", "(i),(i)->(i)", "(i,j),(i,j)->(i,j)"]
-  type_vars: {T: Numeric, U: Numeric}
-  dtypes: {result: "promote(T,U)", casting: "same_kind"}
-  null_policy: propagate
-  kernels:
-    - backend: ruby
-      impl: kumi_sub
-      priority: 10
-
-- name: core.mul
-  domain: core
-  opset: 1
-  class: scalar
-  signature: ["(),()->()", "(i),(i)->(i)", "(i,j),(i,j)->(i,j)"]
-  type_vars: {T: Numeric, U: Numeric}
-  dtypes: {result: "promote(T,U)", casting: "same_kind"}
-  null_policy: propagate
-  algebra: {associative: true, commutative: true, identity: 1, annihilator: 0}
-  kernels:
-    - backend: ruby
-      impl: kumi_mul
-      priority: 10
-
-- name: core.div
-  domain: core
-  opset: 1
-  class: scalar
-  signature: ["(),()->()", "(i),(i)->(i)", "(i,j),(i,j)->(i,j)"]
-  type_vars: {T: Numeric, U: Numeric}
-  dtypes: {result: "promote_float(T,U)", casting: "same_kind"}
-  null_policy: propagate
-  kernels:
-    - backend: ruby
-      impl: kumi_div
-      priority: 10
-
-- name: core.eq
-  domain: core
-  opset: 1
-  class: scalar
-  signature: ["(),()->()", "(i),(i)->(i)", "(i,j),(i,j)->(i,j)"]
-  type_vars: {T: Any, U: Any}
-  dtypes: {result: "bool"}
-  null_policy: propagate
-  algebra: {idempotent: true}
-  kernels:
-    - backend: ruby
-      impl: kumi_eq
-      priority: 10
-
-- name: core.gt
-  domain: core
-  opset: 1
-  class: scalar
-  signature: ["(),()->()", "(i),(i)->(i)"]
-  type_vars: {T: Orderable, U: Orderable}
-  dtypes: {result: "bool"}
-  null_policy: propagate
-  kernels:
-    - backend: ruby
-      impl: kumi_gt
-      priority: 10
-
-- name: core.gte
-  domain: core
-  opset: 1
-  class: scalar
-  signature: ["(),()->()", "(i),(i)->(i)"]
-  type_vars: {T: Orderable, U: Orderable}
-  dtypes: {result: "bool"}
-  null_policy: propagate
-  kernels:
-    - backend: ruby
-      impl: kumi_gte
-      priority: 10
-
-- name: core.and
-  domain: core
-  opset: 1
-  class: scalar
-  signature: ["(),()->()", "(i),(i)->(i)"]
-  type_vars: {B1: Bool, B2: Bool}
-  dtypes: {result: "bool"}
-  null_policy: propagate
-  algebra: {associative: true, commutative: true, identity: true, annihilator: false}
-  vectorization: {short_circuit: left_to_right, mask_aware: true}
-  kernels:
-    - backend: ruby
-      impl: kumi_and
-      priority: 10
-
-- name: core.or
-  domain: core
-  opset: 1
-  class: scalar
-  signature: ["(),()->()", "(i),(i)->(i)"]
-  type_vars: {B1: Bool, B2: Bool}
-  dtypes: {result: "bool"}
-  null_policy: propagate
-  algebra: {associative: true, commutative: true, identity: false, annihilator: true}
-  vectorization: {short_circuit: left_to_right, mask_aware: true}
-  kernels:
-    - backend: ruby
-      impl: kumi_or
-      priority: 10
-
-- name: core.not
-  domain: core
-  opset: 1
-  class: scalar
-  signature: ["()->()", "(i)->(i)"]
-  type_vars: {B: Bool}
-  dtypes: {result: "bool"}
-  null_policy: propagate
-  kernels:
-    - backend: ruby
-      impl: kumi_not
-      priority: 10
-
-# ==================== AGGREGATES (reduce last axis in signature) ==============
-
-- name: agg.sum
-  domain: core
-  opset: 1
-  class: aggregate
-  signature: ["(i)->()", "(i,j)->(i)"]
-  type_vars: {T: Numeric}
-  dtypes: {result: "promote(T)"}
-  null_policy: skip
-  options: {min_count: 0}
-  algebra: {associative: true, commutative: true, identity: 0}
-  kernels:
-    - backend: ruby
-      impl: kumi_sum
-      priority: 10
-
-- name: agg.min
-  domain: core
-  opset: 1
-  class: aggregate
-  signature: ["(i)->()", "(i,j)->(i)"]
-  type_vars: {T: Orderable}
-  dtypes: {result: "T"}
-  null_policy: skip
-  kernels:
-    - backend: ruby
-      impl: kumi_min
-      priority: 10
-
-- name: agg.max
-  domain: core
-  opset: 1
-  class: aggregate
-  signature: ["(i)->()", "(i,j)->(i)"]
-  type_vars: {T: Orderable}
-  dtypes: {result: "T"}
-  null_policy: skip
-  kernels:
-    - backend: ruby
-      impl: kumi_max
-      priority: 10
-
-- name: agg.mean
-  domain: core
-  opset: 1
-  class: aggregate
-  signature: ["(i)->()", "(i,j)->(i)"]
-  type_vars: {T: Numeric}
-  dtypes: {result: "float"}
-  null_policy: skip
-  options: {min_count: 0}
-  kernels:
-    - backend: ruby
-      impl: kumi_mean
-      priority: 10
-
-# ==================== STRUCTURE / SHAPE / JOIN ================================
-
-- name: struct.join
-  domain: struct
-  opset: 1
-  class: structure
-  summary: Align inputs by axes using zip or product
-  signature: ["(i),(i)->(i)@zip", "(i),(j)->(i,j)@product"]
-  null_policy: error_on_missing
-  kernels:
-    - backend: ruby
-      impl: join_zip
-      when: {policy: zip}
-      priority: 10
-    - backend: ruby
-      impl: join_product
-      when: {policy: product}
-      priority: 10
-
-- name: struct.align_to
-  domain: struct
-  opset: 1
-  class: structure
-  signature: ["(i)->(i)", "(i,j)->(i,j)"]
-  traits: {reorders: false}
-  null_policy: error_on_missing
-  kernels:
-    - backend: ruby
-      impl: align_to
-      priority: 10
-
-- name: struct.lift
-  domain: struct
-  opset: 1
-  class: structure
-  signature: ["(i)->(i)", "(i,j)->(i,j)"]
-  summary: Group flat rows back to nested collections based on indices
-  kernels:
-    - backend: ruby
-      impl: lift
-      priority: 10
-
-- name: struct.flatten
-  domain: struct
-  opset: 1
-  class: structure
-  signature: ["(i,j)->(k)"]
-  shape_fn: "flatten_axes(i,j)->k"
-  kernels:
-    - backend: ruby
-      impl: flatten
-      priority: 10
-
-- name: struct.take
-  domain: struct
-  opset: 1
-  class: structure
-  signature: ["(i),(i)->(i)"]  # take(values, indices) elemwise
-  type_vars: {T: Any}
-  dtypes: {result: "T"}
-  null_policy: error
-  kernels:
-    - backend: ruby
-      impl: take
-      priority: 10
-
-- name: struct.size
-  domain: struct
-  opset: 1
-  class: vector
-  signature: ["(i)->()", "(i,j)->()"]
-  dtypes: {result: "int"}
-  null_policy: error
-  kernels:
-    - backend: ruby
-      impl: size
-      priority: 10
-
-# ==================== MASK / CONDITIONAL ======================================
-
-- name: mask.where
-  domain: mask
-  opset: 1
-  class: scalar
-  summary: Ternary select with broadcasting of then/else
-  signature:
-    - "(i),(i),(i)->(i)"
-    - "(i),(),()->(i)"
-    - "(),(i),()->(i)"
-    - "(),(),()->()"
-  type_vars: {B: Bool, T: Any, U: Any}
-  dtypes: {result: "unify(T,U)"}
-  null_policy: propagate
-  vectorization: {mask_aware: true, short_circuit: left_to_right}
-  kernels:
-    - backend: ruby
-      impl: where
-      priority: 10
-
-# ==================== STRING (minimal) ========================================
-
-- name: string.concat
-  domain: string
-  opset: 1
-  class: scalar
-  signature: ["(),()->()", "(i),(i)->(i)"]
-  type_vars: {S1: String, S2: String}
-  dtypes: {result: "string"}
-  null_policy: propagate
-  kernels:
-    - backend: ruby
-      impl: str_concat
-      priority: 10
-
-- name: string.length
-  domain: string
-  opset: 1
-  class: vector
-  signature: ["(i)->(i)", "()->()"]
-  type_vars: {S: String}
-  dtypes: {result: "int"}
-  null_policy: propagate
-  kernels:
-    - backend: ruby
-      impl: str_length
-      priority: 10
-
-# ==================== DATETIME (minimal) ======================================
-
-- name: datetime.add_days
-  domain: datetime
-  opset: 1
-  class: scalar
-  signature: ["(),()->()", "(i),(i)->(i)"]
-  type_vars: {D: DateLike, N: IntLike}
-  dtypes: {result: "datetime"}
-  null_policy: propagate
-  kernels:
-    - backend: ruby
-      impl: dt_add_days
-      priority: 10
-
-- name: datetime.diff_days
-  domain: datetime
-  opset: 1
-  class: scalar
-  signature: ["(),()->()", "(i),(i)->(i)"]
-  type_vars: {D1: DateLike, D2: DateLike}
-  dtypes: {result: "int"}
-  null_policy: propagate
-  kernels:
-    - backend: ruby
-      impl: dt_diff_days
-      priority: 10

data/docs/functions/analyzer_integration.md

@@ -1,199 +0,0 @@
-# Function Signature Analysis Integration
-
-This document describes how NEP-20 function signatures integrate with Kumi's multi-pass analyzer architecture.
-
-## Architecture Overview
-
-Function signature resolution is integrated into the analyzer pipeline through a node index system that allows passes to share metadata efficiently.
-
-```
-┌─────────────────┐    ┌──────────────────────┐    ┌────────────────────┐
-│   Toposorter    │───▶│ FunctionSignaturePass │───▶│   LowerToIRPass    │
-│ Creates node    │    │ Resolves signatures   │    │ Validates metadata │
-│ index by ID     │    │ Attaches metadata     │    │ Emits IR ops       │
-└─────────────────┘    └──────────────────────┘    └────────────────────┘
-```
-
-## Node Index System
-
-### Creation (Toposorter)
-
-The `Toposorter` pass creates a comprehensive index of all nodes in the AST:
-
-```ruby
-# State structure after Toposorter
-state[:node_index] = {
-  object_id_1 => {
-    node: CallExpression_instance,
-    type: "CallExpression",
-    metadata: {}
-  },
-  # ... more nodes
-}
-```
-
-### Population (FunctionSignaturePass)
-
-The `FunctionSignaturePass` populates metadata for `CallExpression` nodes:
-
-```ruby
-# After FunctionSignaturePass
-entry[:metadata] = {
-  signature: Signature_object,           # Full signature object
-  result_axes: [:i, :j],                # Output dimension names  
-  join_policy: :zip,                    # Cross-dimensional policy
-  dropped_axes: [:k],                   # Dimensions eliminated by reductions
-  effective_signature: {                # Normalized for lowering
-    in_shapes: [[:i, :k], [:k, :j]],
-    out_shape: [:i, :j], 
-    join_policy: :zip
-  },
-  dim_env: { i: :i, j: :j, k: :k },    # Dimension variable bindings
-  shape_contract: {                     # Simplified for lowering
-    in: [[:i, :k], [:k, :j]],
-    out: [:i, :j],
-    join: :zip
-  },
-  signature_score: 0                    # Match quality (0 = exact)
-}
-```
-
-### Consumption (LowerToIRPass)
-
-The lowering pass validates and uses the signature metadata:
-
-```ruby
-def validate_signature_metadata(expr, entry)
-  node_index = get_state(:node_index)
-  metadata = node_index[expr.object_id][:metadata]
-  
-  # Validate dropped axes for reductions
-  if entry&.reducer && metadata[:dropped_axes]
-    # Assert axis exists in scope
-  end
-  
-  # Warn about join policies not yet implemented
-  if metadata[:join_policy]
-    # Log warning or feature flag check
-  end
-end
-```
-
-## Pass Integration Points
-
-### 1. Signature Resolution
-
-**Location**: After `BroadcastDetector`, before `TypeChecker`
-
-**Purpose**: Resolve NEP-20 signatures for all function calls
-
-**Input**: 
-- Node index from Toposorter
-- Broadcast metadata (optional)
-- Current function registry
-
-**Output**: Rich signature metadata attached to call nodes
-
-### 2. Type Checking Enhancement
-
-**Integration**: `TypeChecker` can now use signature metadata for enhanced validation:
-
-```ruby
-def validate_function_call(node, errors)
-  # Get resolved signature metadata
-  node_entry = node_index[node.object_id]
-  if node_entry && node_entry[:metadata][:signature]
-    # Use NEP-20 signature for validation
-    validate_nep20_signature(node, node_entry[:metadata], errors)
-  else
-    # Fall back to legacy registry-based validation
-    validate_legacy_signature(node, errors)
-  end
-end
-```
-
-### 3. Lowering Integration
-
-**Integration**: `LowerToIRPass` validates signature consistency and emits appropriate IR:
-
-```ruby  
-when Syntax::CallExpression
-  entry = Kumi::Registry.entry(expr.fn_name)
-  validate_signature_metadata(expr, entry)  # Read-only validation
-  
-  # Use shape contract for IR generation
-  if node_entry = node_index[expr.object_id]
-    contract = node_entry[:metadata][:shape_contract]
-    # Use contract to emit appropriate reduce/join ops
-  end
-```
-
-## Metadata Contract
-
-All passes can rely on this metadata structure for `CallExpression` nodes:
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `:signature` | `Signature` | Full signature object with dimensions |
-| `:result_axes` | `Array<Symbol>` | Output dimension names |
-| `:join_policy` | `Symbol?` | `:zip`, `:product`, or `nil` |
-| `:dropped_axes` | `Array<Symbol>` | Dimensions eliminated (reductions) |
-| `:effective_signature` | `Hash` | Normalized signature for lowering |
-| `:dim_env` | `Hash` | Dimension variable bindings |
-| `:shape_contract` | `Hash` | Simplified contract for IR generation |
-| `:signature_score` | `Integer` | Match quality (0 = exact) |
-
-## Error Handling
-
-Enhanced error messages include signature information:
-
-```ruby
-# Before
-"operator `multiply` expects 2 args, got 3"
-
-# After  
-"Signature mismatch for `multiply` with args (i,j), (k). 
- Candidates: (),()->() | (i),(i)->(i). 
- no matching signature for shapes (i,j), (k)"
-```
-
-## Feature Flags
-
-Control NEP-20 behavior at runtime:
-
-```bash
-export KUMI_ENABLE_FLEX=1    # Enable flexible dimension matching (?)
-export KUMI_ENABLE_BCAST1=1  # Enable broadcastable matching (|1)  
-```
-
-## Future Extensions
-
-The node index architecture supports future enhancements:
-
-### Registry V2 Integration
-```ruby
-# Read signatures from YAML registry
-signatures = RegistryV2.get_function_signatures(node.fn_name)
-```
-
-### Type System Integration
-```ruby
-# Add dtype metadata alongside shape metadata
-metadata[:result_dtype] = infer_result_dtype(args, signature)
-```
-
-### Optimization Metadata
-```ruby
-# Add optimization hints
-metadata[:can_vectorize] = true
-metadata[:memory_access_pattern] = :sequential
-```
-
-## Performance Considerations
-
-- **Node index creation**: O(n) where n = total AST nodes
-- **Signature resolution**: O(k*m) where k = signatures, m = arguments  
-- **Memory overhead**: ~100 bytes per CallExpression node
-- **Pass integration**: Zero performance impact on existing passes
-
-The architecture is designed for extensibility while maintaining backward compatibility with the existing analyzer pipeline.

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).