musa-dsl 0.30.2 → 0.41.0

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

@@ -1,13 +1,120 @@
 require_relative '../series'
 
 module Musa
-
-  # TODO: adapt to series prototyping
-
+  
+  
+  # Markov chain generator for stochastic sequence generation.
+  #
+  # Implements Markov chains that generate sequences of states based on
+  # probabilistic transition rules. Each state transitions to the next
+  # based on defined probabilities, creating pseudo-random but structured
+  # sequences.
+  #
+  # ## Theory
+  #
+  # A Markov chain is a stochastic model describing a sequence of possible
+  # events where the probability of each event depends only on the state
+  # attained in the previous event (memoryless property).
+  #
+  # ## Transition Types
+  #
+  # - **Array**: Equal probability between all options
+  #   - `{ a: [:b, :c] }` → 50% chance of :b, 50% chance of :c
+  #
+  # - **Hash**: Weighted probabilities
+  #   - `{ a: { b: 0.2, c: 0.8 } }` → 20% :b, 80% :c
+  #   - Probabilities are normalized (don't need to sum to 1.0)
+  #
+  # - **Proc**: Algorithmic transitions based on history
+  #   - `{ a: proc { |history| history.size.even? ? :b : :c } }`
+  #   - Proc receives full history and returns next state
+  #
+  # ## Musical Applications
+  #
+  # - Generate melodic sequences with style-based transitions
+  # - Create rhythmic patterns with probabilistic variation
+  # - Produce chord progressions with weighted likelihood
+  # - Build dynamic musical structures with emergent behavior
+  #
+  # @example Equal probability transitions
+  #   markov = Musa::Markov::Markov.new(
+  #     start: :a,
+  #     finish: :x,
+  #     transitions: {
+  #       a: [:b, :c],      # 50/50 chance
+  #       b: [:a, :c],
+  #       c: [:a, :b, :x]
+  #     }
+  #   ).i
+  #
+  #   markov.to_a  # => [:a, :c, :b, :a, :b, :c, :x]
+  #
+  # @example Weighted probability transitions
+  #   markov = Musa::Markov::Markov.new(
+  #     start: :a,
+  #     finish: :x,
+  #     transitions: {
+  #       a: { b: 0.2, c: 0.8 },  # 20% b, 80% c
+  #       b: { a: 0.3, c: 0.7 },  # 30% a, 70% c
+  #       c: [:a, :b, :x]         # Equal probability
+  #     }
+  #   ).i
+  #
+  # @example Algorithmic transitions with history
+  #   markov = Musa::Markov::Markov.new(
+  #     start: :a,
+  #     finish: :x,
+  #     transitions: {
+  #       a: { b: 0.2, c: 0.8 },
+  #       # Transition based on history length
+  #       b: proc { |history| history.size.even? ? :a : :c },
+  #       c: [:a, :b, :x]
+  #     }
+  #   ).i
+  #
+  # @example Musical pitch transitions
+  #   # Create melodic sequence with style-based transitions
+  #   melody = Musa::Markov::Markov.new(
+  #     start: 60,  # Middle C
+  #     finish: nil,  # Infinite
+  #     transitions: {
+  #       60 => { 62 => 0.4, 64 => 0.3, 59 => 0.3 },  # C → D/E/B
+  #       62 => { 60 => 0.3, 64 => 0.4, 67 => 0.3 },  # D → C/E/G
+  #       64 => [60, 62, 65, 67],                      # E → C/D/F/G
+  #       # ... more transitions
+  #     }
+  #   ).i.max_size(16).to_a
+  #
+  # @see Musa::Series::Serie Series interface for chaining operations
+  # @see Musa::Extension::SmartProcBinder Smart procedure binding for history-based transitions
+  # @see https://en.wikipedia.org/wiki/Markov_chain Markov chain (Wikipedia)
+  # @see https://en.wikipedia.org/wiki/Stochastic_process Stochastic process (Wikipedia)
+  # @see https://en.wikipedia.org/wiki/Markov_chain#Music Markov chains in music (Wikipedia)
   module Markov
+    # Markov chain serie generator.
+    #
+    # Generates sequences of states following probabilistic transition rules.
+    # Implements {Musa::Series::Serie} interface for integration with series operations.
     class Markov
+      # TODO: adapt to series prototyping
       include Musa::Series::Serie.base
 
+      # Creates Markov chain generator.
+      #
+      # @param transitions [Hash] state transition rules
+      #   Keys are states, values are next state definitions (Array, Hash, or Proc)
+      # @param start [Object] initial state
+      # @param finish [Object, nil] terminal state (nil for infinite)
+      # @param random [Random, Integer, nil] random number generator or seed
+      #
+      # @example
+      #   markov = Markov.new(
+      #     transitions: { a: [:b, :c], b: [:a, :c], c: [:a, :b, :x] },
+      #     start: :a,
+      #     finish: :x
+      #   )
+      #
+      # @return [void]
       def initialize(transitions:, start:, finish: nil, random: nil)
         @transitions = transitions.clone.freeze
 
@@ -23,17 +130,39 @@ module Musa
         init
       end
 
+      # @return [Object] starting state
       attr_accessor :start
+
+      # @return [Object, nil] finishing state (nil for infinite)
       attr_accessor :finish
+
+      # @return [Random] random number generator
       attr_accessor :random
+
+      # @return [Hash] transition rules (frozen)
       attr_accessor :transitions
 
+      # Initializes serie instance state.
+      #
+      # @api private
       private def _init
         @current = nil
         @finished = false
         @history = []
       end
 
+      # Generates next value in Markov chain.
+      #
+      # Selects next state based on current state's transition rules.
+      # Handles Array (equal probability), Hash (weighted), and Proc (algorithmic)
+      # transitions.
+      #
+      # @return [Object, nil] next state, or nil if finished
+      #
+      # @raise [RuntimeError] if no transition defined for current state
+      # @raise [ArgumentError] if transition type is not Array, Hash, or Proc
+      #
+      # @api private
       private def _next_value
         if @finished
           @current = nil
@@ -75,6 +204,9 @@ module Musa
         @current
       end
 
+      # Checks if Markov chain is infinite.
+      #
+      # @return [Boolean] true if no finish state defined
       def infinite?
         @finish.nil?
       end

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

@@ -1,21 +1,174 @@
 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
+      #
+      # @return [void]
       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 +206,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,36 +248,75 @@ 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
 
+        # @return [void]
+        # @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
         end
 
+        # Checks if end condition is defined.
+        #
+        # @return [Boolean] true if ended_when was called
+        #
+        # @api private
         def _has_ending?
           !@_ended_when.nil?
         end
 
+        # Evaluates end condition for object.
+        #
+        # @param object [Object] object to check
+        # @param history [Array] object history
+        # @param parameters [Hash] additional parameters
+        #
+        # @return [Boolean] true if object should end
+        #
+        # @api private
         def _ended?(object, history, **parameters)
           if @_ended_when
             with object, history, **parameters, &@_ended_when
@@ -117,11 +328,21 @@ module Musa
         class GrowRule
           attr_reader :name
 
+          # @param name [String] rule name
+          #
+          # @return [void]
           def initialize(name, &block)
             @name = name
             @block = block
           end
 
+          # Generates possible branched objects.
+          #
+          # @param object [Object] object to branch
+          # @param history [Array] object history
+          # @param parameters [Hash] additional parameters
+          #
+          # @return [Array<Object>] branched objects
           def generate_possibilities(object, history, **parameters)
             # TODO: optimize context using only one instance for all genereate_possibilities calls
             context = GrowRuleEvalContext.new
@@ -135,10 +356,16 @@ module Musa
 
             attr_reader :_branches
 
+            # @return [void]
             def initialize
               @_branches = []
             end
 
+            # Records a branched object.
+            #
+            # @param object [Object] branched object
+            #
+            # @return [self]
             def branch(object)
               @_branches << object
               self
@@ -153,11 +380,21 @@ module Musa
         class CutRule
           attr_reader :reason
 
+          # @param reason [String] rejection reason
+          #
+          # @return [void]
           def initialize(reason, &block)
             @reason = reason
             @block = block
           end
 
+          # Checks if object should be rejected.
+          #
+          # @param object [Object] object to check
+          # @param history [Array] object history
+          # @param parameters [Hash] additional parameters
+          #
+          # @return [Array<String>, nil] rejection reasons or nil if not rejected
           def rejects?(object, history, **parameters)
             # TODO: optimize context using only one instance for all rejects? checks
             context = CutRuleEvalContext.new
@@ -173,10 +410,16 @@ module Musa
 
             attr_reader :_secondary_reasons
 
+            # @return [void]
             def initialize
               @_secondary_reasons = []
             end
 
+            # Marks object for pruning.
+            #
+            # @param secondary_reason [String, nil] additional reason detail
+            #
+            # @return [self]
             def prune(secondary_reason = nil)
               @_secondary_reasons << secondary_reason
               self
@@ -191,9 +434,26 @@ 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
 
+        # @param object [Object, nil] node object
+        # @param parent [Node, nil] parent node
+        #
+        # @return [void]
+        #
+        # @api private
         def initialize(object = nil, parent = nil)
           @parent = parent
           @children = []
@@ -203,15 +463,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 +500,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 +523,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 +546,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 ||= []