musa-dsl 0.30.2 → 0.40.0

data/lib/musa-dsl/generative/rules.rb

@@ -1,21 +1,172 @@
 require_relative '../core-ext/smart-proc-binder'
 require_relative '../core-ext/with'
 
-# TODO: hacer que pueda funcionar en tiempo real? le vas suministrando seeds y le vas diciendo qué opción has elegido (p.ej. para hacer un armonizador en tiempo real)
-# TODO: esto mismo sería aplicable en otros generadores? variatio/darwin? generative-grammar? markov?
-# TODO: optimizar la llamada a .with que internamente genera cada vez un SmartProcBinder; podría generarse sólo una vez por cada &block
-
 module Musa
+  # Rule-based production system with growth and pruning.
+  #
+  # Rules implements a production system that generates tree structures
+  # by applying growth rules to produce branches and pruning rules to
+  # eliminate invalid paths. Similar to L-systems and production systems
+  # in formal grammars, but with validation and constraint satisfaction.
+  #
+  # ## Core Concepts
+  #
+  # - **Grow Rules**: Transform objects into new possibilities (branches)
+  # - **Cut Rules**: Prune branches that violate constraints
+  # - **End Condition**: Mark branches as complete
+  # - **Tree**: Hierarchical structure of all valid possibilities
+  # - **History**: Path from root to current node
+  # - **Combinations**: All valid complete paths through tree
+  #
+  # ## Generation Process
+  #
+  # 1. **Seed**: Start with initial object(s)
+  # 2. **Grow**: Apply grow rules sequentially to create branches
+  # 3. **Validate**: Apply cut rules to prune invalid branches
+  # 4. **Check End**: Mark branches meeting end condition
+  # 5. **Recurse**: Continue growing non-ended branches
+  # 6. **Collect**: Gather all valid complete paths
+  #
+  # ## Rule Application
+  #
+  # Rules are applied in definition order. Each grow rule can produce
+  # multiple branches via `branch`. Cut rules can prune with `prune`.
+  # The system tracks history (path to current node) for context-aware
+  # rule application.
+  #
+  # ## Musical Applications
+  #
+  # - Generate harmonic progressions with voice leading rules
+  # - Create melodic variations with contour constraints
+  # - Produce rhythmic patterns following metric rules
+  # - Build counterpoint with species rules
+  # - Generate chord voicings with spacing constraints
+  #
+  # @example Basic chord progression rules
+  #   rules = Musa::Rules::Rules.new do
+  #     # Generate possible next chords
+  #     grow 'next chord' do |chord, history|
+  #       case chord
+  #       when :I   then branch(:ii); branch(:IV); branch(:V)
+  #       when :ii  then branch(:V); branch(:vii)
+  #       when :IV  then branch(:I); branch(:V)
+  #       when :V   then branch(:I); branch(:vi)
+  #       when :vi  then branch(:ii); branch(:IV)
+  #       when :vii then branch(:I)
+  #       end
+  #     end
+  #
+  #     # Avoid parallel fifths
+  #     cut 'parallel fifths' do |chord, history|
+  #       prune if has_parallel_fifths?(history + [chord])
+  #     end
+  #
+  #     # End after 4 chords
+  #     ended_when do |chord, history|
+  #       history.size == 4
+  #     end
+  #   end
+  #
+  #   tree = rules.apply([:I])
+  #   progressions = tree.combinations
+  #   # => [[:I, :ii, :V, :I], [:I, :IV, :V, :I], ...]
+  #
+  # @example Melodic contour rules with parameters
+  #   rules = Musa::Rules::Rules.new do
+  #     grow 'next note' do |pitch, history, max_interval:|
+  #       # Try intervals within max_interval
+  #       (-max_interval..max_interval).each do |interval|
+  #         branch pitch + interval unless interval.zero?
+  #       end
+  #     end
+  #
+  #     cut 'range limit' do |pitch, history|
+  #       prune if pitch < 60 || pitch > 84  # C4 to C6
+  #     end
+  #
+  #     cut 'no large leaps' do |pitch, history|
+  #       prune if history.last && (pitch - history.last).abs > 7
+  #     end
+  #
+  #     ended_when do |pitch, history|
+  #       history.size == 8  # 8-note melody
+  #     end
+  #   end
+  #
+  #   tree = rules.apply([60], max_interval: 3)
+  #   melodies = tree.combinations
+  #
+  # @example Rhythm pattern generation
+  #   rules = Musa::Rules::Rules.new do
+  #     grow 'add duration' do |pattern, history, remaining:|
+  #       [1/4r, 1/8r, 1/16r].each do |dur|
+  #         if dur <= remaining
+  #           branch pattern + [dur]
+  #         end
+  #       end
+  #     end
+  #
+  #     cut 'too many sixteenths' do |pattern, history|
+  #       sixteenths = pattern.count { |d| d == 1/16r }
+  #       prune if sixteenths > 4
+  #     end
+  #
+  #     ended_when do |pattern, history, remaining:|
+  #       pattern.sum >= remaining
+  #     end
+  #   end
+  #
+  #   tree = rules.apply([], remaining: 1r)  # One bar
+  #   rhythms = tree.combinations
+  #
+  # @see Rules Main rule-based generator class
+  # @see Musa::Extension::SmartProcBinder Smart procedure binding for rule evaluation
+  # @see Musa::Extension::Arrayfy Array conversion for seed objects
+  # @see Musa::Extension::With DSL context management for rule definitions
+  # @see https://en.wikipedia.org/wiki/Production_system_(computer_science) Production systems (Wikipedia)
+  # @see https://en.wikipedia.org/wiki/L-system L-systems (Wikipedia)
   module Rules
+    # TODO: hacer que pueda funcionar en tiempo real? le vas suministrando seeds y le vas diciendo qué opción has elegido (p.ej. para hacer un armonizador en tiempo real)
+    # TODO: esto mismo sería aplicable en otros generadores? variatio/darwin? generative-grammar? markov?
+    # TODO: optimizar la llamada a .with que internamente genera cada vez un SmartProcBinder; podría generarse sólo una vez por cada &block
+    
     using Musa::Extension::Arrayfy
 
+    # Rule-based generator with growth and pruning.
+    #
+    # Applies grow/cut rules to generate tree of valid possibilities.
     class Rules
       include Musa::Extension::With
 
+      # Creates rule system with defined rules.
+      #
+      # @yield rule definition DSL block
+      # @yieldreturn [void]
+      #
+      # @example
+      #   rules = Rules.new do
+      #     grow 'generate' { |obj| branch new_obj }
+      #     cut 'validate' { |obj| prune if invalid?(obj) }
+      #     ended_when { |obj| complete?(obj) }
+      #   end
       def initialize(&block)
         @dsl = RulesEvalContext.new(&block)
       end
 
+      # Generates possibility tree from object.
+      #
+      # Recursively applies grow rules to create branches, cut rules to
+      # prune invalid paths, and end conditions to mark complete branches.
+      #
+      # @param object [Object] object to expand
+      # @param confirmed_node [Node, nil] confirmed parent node (for history)
+      # @param node [Node, nil] current node being built
+      # @param grow_rules [Array<GrowRule>, nil] rules to apply
+      # @param parameters [Hash] additional parameters for rules
+      #
+      # @return [Node] root node of possibility tree
+      #
+      # @api private
       def generate_possibilities(object, confirmed_node = nil, node = nil, grow_rules = nil, **parameters)
         node ||= Node.new
         grow_rules ||= @dsl._grow_rules
@@ -53,6 +204,25 @@ module Musa
         node
       end
 
+      # Applies rules to seed objects sequentially.
+      #
+      # Processes list of seed objects in sequence, generating possibilities
+      # from each confirmed endpoint of previous seed. Returns tree of all
+      # valid combination paths.
+      #
+      # @param object_or_list [Object, Array] seed object(s) to process
+      # @param node [Node, nil] root node (creates if nil)
+      # @param parameters [Hash] additional parameters for rules
+      #
+      # @return [Node] root node with all combination paths
+      #
+      # @example Single seed
+      #   tree = rules.apply(:I)
+      #   tree.combinations  # => [[:I, :ii, :V, :I], ...]
+      #
+      # @example Multiple seeds
+      #   tree = rules.apply([:I, :ii, :V])
+      #   tree.combinations  # => combinations starting from each seed
       def apply(object_or_list, node = nil, **parameters)
         list = object_or_list.arrayfy.clone
 
@@ -76,27 +246,51 @@ module Musa
         node
       end
 
+      # DSL context for rule definitions.
+      #
+      # @api private
       class RulesEvalContext
         include Musa::Extension::With
 
+        # @return [Array<GrowRule>] grow rules
+        # @return [Proc, nil] end condition
+        # @return [Array<CutRule>] cut rules
         attr_reader :_grow_rules, :_ended_when, :_cut_rules
 
+        # @api private
         def initialize(&block)
           @_grow_rules = []
           @_cut_rules = []
           with &block
         end
 
+        # Defines grow rule.
+        #
+        # @param name [String] rule name for debugging
+        # @yield [object, history, **params] rule block
+        # @return [self]
+        # @api private
         def grow(name, &block)
           @_grow_rules << GrowRule.new(name, &block)
           self
         end
 
+        # Defines end condition.
+        #
+        # @yield [object, history, **params] condition block
+        # @return [self]
+        # @api private
         def ended_when(&block)
           @_ended_when = block
           self
         end
 
+        # Defines cut/pruning rule.
+        #
+        # @param reason [String] rejection reason
+        # @yield [object, history, **params] pruning block
+        # @return [self]
+        # @api private
         def cut(reason, &block)
           @_cut_rules << CutRule.new(reason, &block)
           self
@@ -191,9 +385,21 @@ module Musa
 
       private_constant :RulesEvalContext
 
+      # Tree node representing possibility in generation.
+      #
+      # Nodes form tree structure of generation possibilities.
+      # Each node has object, parent, children, rejection status, and end flag.
+      #
+      # @attr_reader parent [Node, nil] parent node
+      # @attr_reader children [Array<Node>] child nodes
+      # @attr_reader object [Object, nil] node object
+      # @attr_reader rejected [String, Array<String>, nil] rejection reason(s)
+      #
+      # @api private
       class Node
         attr_reader :parent, :children, :object, :rejected
 
+        # @api private
         def initialize(object = nil, parent = nil)
           @parent = parent
           @children = []
@@ -203,15 +409,31 @@ module Musa
           @rejected = nil
         end
 
+        # Adds child node.
+        #
+        # @param object [Object] child object
+        # @return [Node] created child node
+        # @api private
         def add(object)
           Node.new(object, self).tap { |n| @children << n }
         end
 
+        # Marks node as rejected.
+        #
+        # @param rejection [String, Array<String>] rejection reason(s)
+        # @return [self]
+        # @api private
         def reject!(rejection)
           @rejected = rejection
           self
         end
 
+        # Marks node as ended/complete.
+        #
+        # Propagates rejection if all children rejected.
+        #
+        # @return [self]
+        # @api private
         def mark_as_ended!
           @children.each(&:update_rejection_by_children!)
 
@@ -224,10 +446,18 @@ module Musa
           self
         end
 
+        # Checks if node is ended.
+        #
+        # @return [Boolean]
+        # @api private
         def ended?
           @ended
         end
 
+        # Returns path from root to this node.
+        #
+        # @return [Array<Object>] history of objects
+        # @api private
         def history
           objects = []
           n = self
@@ -239,6 +469,13 @@ module Musa
           objects.reverse
         end
 
+        # Collects objects from ended leaf nodes.
+        #
+        # Recursively gathers objects from all valid ended branches,
+        # excluding rejected paths.
+        #
+        # @return [Array<Object>] objects from valid endpoints
+        # @api private
         def fish
           fished = []
 
@@ -255,6 +492,23 @@ module Musa
           fished
         end
 
+        # Returns all valid combination paths.
+        #
+        # Recursively builds complete paths from root to all valid
+        # leaf nodes, excluding rejected branches.
+        #
+        # @param parent_combination [Array, nil] parent path
+        #
+        # @return [Array<Array<Object>>] all valid complete paths
+        #
+        # @example
+        #   tree.combinations
+        #   # => [
+        #   #   [:I, :ii, :V, :I],
+        #   #   [:I, :IV, :V, :I],
+        #   #   ...
+        #   # ]
+        # @api private
         def combinations(parent_combination = nil)
           parent_combination ||= []
 

data/lib/musa-dsl/generative/variatio.rb

@@ -2,14 +2,147 @@ require_relative '../core-ext/smart-proc-binder'
 require_relative '../core-ext/arrayfy'
 require_relative '../core-ext/with'
 
-# TODO: permitir definir un variatio a través de llamadas a métodos y/o atributos, además de a través del block del constructor
-
 module Musa
+  # Combinatorial variation generator with Cartesian product.
+  #
+  # Variatio generates all possible combinations of parameter values across
+  # defined fields, creating comprehensive variation sets. Uses Cartesian
+  # product to produce exhaustive parameter combinations, then constructs
+  # objects and applies attribute modifications.
+  #
+  # ## Core Concepts
+  #
+  # - **Fields**: Named parameters with option sets
+  # - **Fieldsets**: Nested field groups with their own options
+  # - **Constructor**: Creates base objects from field values
+  # - **with_attributes**: Modifies objects with field/fieldset values
+  # - **Finalize**: Post-processes completed objects
+  # - **Variations**: All Cartesian product combinations
+  #
+  # ## Generation Process
+  #
+  # 1. **Define**: Specify fields, fieldsets, constructor, attributes, finalize
+  # 2. **Combine**: Calculate Cartesian product of all field options
+  # 3. **Construct**: Create objects using constructor with each combination
+  # 4. **Attribute**: Apply with_attributes blocks for each combination
+  # 5. **Finalize**: Run finalize block on completed objects
+  # 6. **Return**: Array of all generated variations
+  #
+  # ## Musical Applications
+  #
+  # - Generate all variations of a musical motif
+  # - Create comprehensive parameter sweeps for synthesis
+  # - Produce complete harmonic permutations
+  # - Build exhaustive rhythm pattern combinations
+  #
+  # @example Basic field variations
+  #   variatio = Musa::Variatio::Variatio.new :chord do
+  #     field :root, [60, 64, 67]     # C, E, G
+  #     field :type, [:major, :minor]
+  #
+  #     constructor do |root:, type:|
+  #       { root: root, type: type }
+  #     end
+  #   end
+  #
+  #   variations = variatio.run
+  #   # => [
+  #   #   { root: 60, type: :major },
+  #   #   { root: 60, type: :minor },
+  #   #   { root: 64, type: :major },
+  #   #   { root: 64, type: :minor },
+  #   #   { root: 67, type: :major },
+  #   #   { root: 67, type: :minor }
+  #   # ]
+  #   # 3 roots × 2 types = 6 variations
+  #
+  # @example Override field options at runtime
+  #   variatio = Musa::Variatio::Variatio.new :object do
+  #     field :a, 1..10
+  #     field :b, [:alfa, :beta, :gamma]
+  #
+  #     constructor { |a:, b:| { a: a, b: b } }
+  #   end
+  #
+  #   # Override :a to limit variations
+  #   variatio.on(a: 1..3)
+  #   # => 3 × 3 = 9 variations instead of 10 × 3 = 30
+  #
+  # @example Nested fieldsets with attributes
+  #   variatio = Musa::Variatio::Variatio.new :synth do
+  #     field :wave, [:saw, :square]
+  #     field :cutoff, [500, 1000, 2000]
+  #
+  #     constructor do |wave:, cutoff:|
+  #       { wave: wave, cutoff: cutoff, lfo: {} }
+  #     end
+  #
+  #     # Nested fieldset for LFO parameters
+  #     fieldset :lfo, [:vibrato, :tremolo] do
+  #       field :rate, [4, 8]
+  #       field :depth, [0.1, 0.5]
+  #
+  #       with_attributes do |synth:, lfo:, rate:, depth:|
+  #         synth[:lfo][lfo] = { rate: rate, depth: depth }
+  #       end
+  #     end
+  #   end
+  #
+  #   variations = variatio.run
+  #   # => 2 waves × 3 cutoffs × 2 lfo types × 2 rates × 2 depths = 48 variations
+  #
+  # @example With finalize block
+  #   variatio = Musa::Variatio::Variatio.new :note do
+  #     field :pitch, [60, 62, 64]
+  #     field :velocity, [64, 96, 127]
+  #
+  #     constructor { |pitch:, velocity:| { pitch: pitch, velocity: velocity } }
+  #
+  #     finalize do |note:|
+  #       note[:loudness] = note[:velocity] / 127.0
+  #       note[:dynamics] = case note[:velocity]
+  #         when 0..48 then :pp
+  #         when 49..80 then :mf
+  #         else :ff
+  #       end
+  #     end
+  #   end
+  #
+  # @see Variatio Main combinatorial variation generator class
+  # @see Musa::Extension::SmartProcBinder Smart procedure binding for constructor/finalize blocks
+  # @see Musa::Extension::Arrayfy Array conversion utilities for field options
+  # @see Musa::Extension::With DSL context management for field definitions
+  # @see https://en.wikipedia.org/wiki/Cartesian_product Cartesian product (Wikipedia)
+  # @see https://en.wikipedia.org/wiki/Variation_(mathematics) Variation in mathematics (Wikipedia)
+  #
+  # @api public
   module Variatio
     using Musa::Extension::Arrayfy
     using Musa::Extension::ExplodeRanges
 
+    # TODO: permitir definir un variatio a través de llamadas a métodos y/o atributos, además de a través del block del constructor
+
+    # Combinatorial variation generator.
+    #
+    # Generates all combinations of field values using Cartesian product,
+    # constructs objects, applies attributes, and optionally finalizes.
     class Variatio
+      # Creates variation generator with field definitions.
+      #
+      # @param instance_name [Symbol] name for object parameter in blocks
+      #
+      # @yield DSL block defining fields, constructor, attributes, finalize
+      # @yieldreturn [void]
+      #
+      # @raise [ArgumentError] if instance_name not a symbol
+      # @raise [ArgumentError] if no block given
+      #
+      # @example
+      #   variatio = Variatio.new :obj do
+      #     field :x, [1, 2, 3]
+      #     field :y, [:a, :b]
+      #     constructor { |x:, y:| { x: x, y: y } }
+      #   end
       def initialize(instance_name, &block)
         raise ArgumentError, 'instance_name should be a symbol' unless instance_name.is_a?(Symbol)
         raise ArgumentError, 'block is needed' unless block
@@ -23,6 +156,29 @@ module Musa
         @finalize = main_context._finalize
       end
 
+      # Generates variations with runtime field value overrides.
+      #
+      # Allows overriding field options at generation time, useful for
+      # limiting variation space or parameterizing generation.
+      #
+      # @param values [Hash{Symbol => Array, Range}] field overrides
+      #   Keys are field names, values are option arrays or ranges
+      #
+      # @return [Array] all generated variation objects
+      #
+      # @example Override field values
+      #   variatio = Variatio.new :obj do
+      #     field :x, 1..10
+      #     field :y, [:a, :b, :c]
+      #     constructor { |x:, y:| { x: x, y: y } }
+      #   end
+      #
+      #   # Default: 10 × 3 = 30 variations
+      #   variatio.run.size  # => 30
+      #
+      #   # Override :x to limit variations
+      #   variatio.on(x: 1..3).size  # => 3 × 3 = 9
+      #   variatio.on(x: [5], y: [:a]).size  # => 1 × 1 = 1
       def on(**values)
         constructor_binder = Musa::Extension::SmartProcBinder::SmartProcBinder.new @constructor
         finalize_binder = Musa::Extension::SmartProcBinder::SmartProcBinder.new @finalize if @finalize
@@ -60,6 +216,25 @@ module Musa
         combinations
       end
 
+      # Generates all variations with default field values.
+      #
+      # Equivalent to calling {#on} with no overrides.
+      #
+      # @return [Array] all generated variation objects
+      #
+      # @example
+      #   variatio = Variatio.new :obj do
+      #     field :x, [1, 2, 3]
+      #     field :y, [:a, :b]
+      #     constructor { |x:, y:| { x: x, y: y } }
+      #   end
+      #
+      #   variations = variatio.run
+      #   # => [
+      #   #   { x: 1, y: :a }, { x: 1, y: :b },
+      #   #   { x: 2, y: :a }, { x: 2, y: :b },
+      #   #   { x: 3, y: :a }, { x: 3, y: :b }
+      #   # ]
       def run
         on
       end
@@ -199,6 +374,12 @@ module Musa
 
       private_constant :A2
 
+      # Internal tree node for attribute application phase.
+      #
+      # Manages execution of `with_attributes` blocks during variation generation.
+      # Coordinates attribute application across field hierarchy.
+      #
+      # @api private
       class B
         attr_reader :parameter_name, :options, :affected_field_names, :blocks, :inner
 
@@ -245,26 +426,46 @@ module Musa
         private
       end
 
+      # DSL context for fieldset definition.
+      #
+      # @api private
       class FieldsetContext
         include Musa::Extension::With
 
+        # @return [Fieldset] defined fieldset
         attr_reader :_fieldset
 
+        # @api private
         def initialize(name, options = nil, &block)
           @_fieldset = Fieldset.new name, options.arrayfy.explode_ranges
 
           with &block
         end
 
+        # Defines a field with options.
+        #
+        # @param name [Symbol] field name
+        # @param options [Array, Range, nil] field option values
+        # @api private
         def field(name, options = nil)
           @_fieldset.components << Field.new(name, options.arrayfy.explode_ranges)
         end
 
+        # Defines nested fieldset.
+        #
+        # @param name [Symbol] fieldset name
+        # @param options [Array, Range, nil] fieldset option values
+        # @yield fieldset DSL block
+        # @api private
         def fieldset(name, options = nil, &block)
           fieldset_context = FieldsetContext.new name, options, &block
           @_fieldset.components << fieldset_context._fieldset
         end
 
+        # Adds attribute modification block.
+        #
+        # @yield attribute modification block
+        # @api private
         def with_attributes(&block)
           @_fieldset.with_attributes << block
         end
@@ -272,9 +473,15 @@ module Musa
 
       private_constant :FieldsetContext
 
+      # DSL context for main Variatio configuration.
+      #
+      # @api private
       class MainContext < FieldsetContext
+        # @return [Proc] constructor block
+        # @return [Proc, nil] finalize block
         attr_reader :_constructor, :_finalize
 
+        # @api private
         def initialize(&block)
           @_constructor = nil
           @_finalize = nil
@@ -282,10 +489,18 @@ module Musa
           super :_maincontext, [nil], &block
         end
 
+        # Defines object constructor.
+        #
+        # @yield constructor block receiving field values
+        # @api private
         def constructor(&block)
           @_constructor = block
         end
 
+        # Defines finalize block.
+        #
+        # @yield finalize block receiving completed object
+        # @api private
         def finalize(&block)
           @_finalize = block
         end