csp-resolver 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a8b89688ec5b6907524a3b31a8159a7c78dbe61578ed77e47ddeddfb956777d4
+  data.tar.gz: 2791072bb632b2a19151ba5bd60c2ecbdb2923edfd727a0e3ccb6c1f30546ecb
+SHA512:
+  metadata.gz: 0ec7e93632f200c4ffc71d702146acfc64e3395c8a77c987f0190dd64f6f2b377d858e3f8cbbb2341b70d8476ce86719a853359d043546eb0e7a8df374a73bf8
+  data.tar.gz: a0f7552bd93a53f387052eeba3b8a3cb411671d362e0bbb1524b41d176acd0d842d29d4e1be08e847d3c6b2e33dc5588dedebb1de2932018f57bb3a97b9d4a33

data/.rubocop.yml

@@ -0,0 +1,28 @@
+AllCops:
+  TargetRubyVersion: 2.5
+  NewCops: enable
+  SuggestExtensions: false
+Metrics/BlockLength:
+  Exclude:
+    - spec/**/*.rb
+Metrics/ClassLength:
+  Max: 200
+Metrics/MethodLength:
+  Max: 20
+Layout/FirstArrayElementIndentation:
+  EnforcedStyle: consistent
+Layout/FirstHashElementIndentation:
+  EnforcedStyle: consistent
+Layout/HashAlignment:
+  EnforcedLastArgumentHashStyle: always_inspect
+Layout/MultilineMethodCallIndentation:
+  EnforcedStyle: indented
+Style/Documentation:
+  Enabled: false
+Layout/EndAlignment:
+  EnforcedStyleAlignWith: variable
+Style/ObjectThen:
+  EnforcedStyle: yield_self
+Naming/FileName:
+  Exclude:
+    - 'lib/csp-resolver.rb'

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2024 Rebase, André Benjamim, Gustavo Alberto.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,260 @@
+# CSP Resolver
+The `csp-resolver` gem is a powerful tool designed to solve [Constraint Satisfaction Problems](https://en.wikipedia.org/wiki/Constraint_satisfaction_problem) (CSPs), which are mathematical questions defined by strict constraints that must be met. This tool is suitable for a wide range of applications, from scheduling and planning to configuring complex systems.
+
+## Getting Started
+### Requirements
+**Ruby** >= 2.5.8
+
+### Installing
+You can install using the following command:
+```bash
+gem install "csp-resolver"
+```
+
+If you prefer using Bundler, add the following line to your Gemfile:
+```bash
+gem "csp-resolver"
+```
+
+Then install it:
+```bash
+$ bundle install
+```
+
+## Usage
+
+### **Setup a problem to be solved**
+To setup a problem we need to require the gem and initialize the CSP:
+
+```ruby
+require 'csp-resolver'
+
+problem = CSP::Problem.new
+```
+
+### **Adding variables and domains**
+
+To add variables and domains you can use the **`add_variable`** method:
+
+```ruby
+variable = 'A'
+domains = %w[red green blue]
+
+problem.add_variable(variable, domains: domains)
+```
+
+If some variables share the same domains, you can use **`add_variables`** (plural) for easier setup:
+```ruby
+variables = %w[B C]
+domains = %w[red green blue]
+
+problem.add_variables(variables, domains: domains)
+
+# is the same as
+problem.add_variable('B', domains: domains)
+problem.add_variable('C', domains: domains)
+```
+
+### **Adding constraints**
+There are three ways of adding a constraint: **built-in methods**, **custom block**, or **custom constraint class**.
+
+#### **Using built-in methods**
+Setting a list of variables to be unique between them:
+```ruby
+# A != B != C
+problem.unique(%w[A B])
+problem.unique(%w[A C])
+problem.unique(%w[C B])
+
+# same as
+problem.unique(%w[A B C])
+```
+
+Setting all variable assignments to be different:
+```ruby
+# A != B != C
+# It will consider all variables of CSP automatically
+problem.all_different
+```
+
+#### **Using a custom block**
+You can use the **`add_constraint`** method passing `variables` and a block to create custom validations:
+
+```ruby
+# Set B != C and B != A
+problem.add_constraint(variables: %w[B C A]) { |b, c, a| b != c && b != a }
+```
+
+The block parameters should correspond to the order of the variables provided.
+
+#### **Using a custom constraint class**
+To create a custom constraint class it'll need to answer if an assignment satisfies a condition for a group of variables.
+
+The easiest way to do this is inheriting from **`CSP::Constraint`**:
+
+```ruby
+class MyCustomConstraint < CSP::Constraint
+end
+```
+
+Now the **`CustomConstraint`** can receive a list of variables which we will use to check if their assigned values conform to the constraint's rule.
+
+```ruby
+variables = %w[A B C]
+
+constraint = MyCustomConstraint.new(variables)
+
+# It can answer the arity for constraint
+constraint.unary? # => false
+constraint.binary? # => false
+constraint.arity # => 3
+```
+
+##### **Implementing the constraint rule**
+To determinate if the solution satisfies or not a constraint we need to implement the **`satisfies?`** method. This method receives a hash containing the current variables assignments.
+
+```ruby
+# Variables can't have the color purple
+
+class MyCustomConstraint < CSP::Constraint
+  def satisfies?(assignment = {})
+    # While not all variables for this constraint are assigned,
+    # consider that it doesn't violates the constraint.
+    return true if variables.all? { |variable| assignment[variable] }
+
+    variables.all? { |variable| assignment[variable] != 'purple' }
+  end
+end
+```
+
+##### **Adding the constraint to CSP**
+To add the constraint we must instantiate it and pass the object to **`add_constraint`**:
+```ruby
+problem = CSP::Problem.new
+problem.add_variables(%w[A B C], domains: %w[purple red green blue])
+
+# B can't have the color purple
+constraint = MyCustomConstraint.new(%w[B])
+
+# Add the B != purple constraint
+problem.add_constraint(constraint)
+```
+
+##### **The constructor**
+
+The default constructor expects to receive an array of variables to apply the constraint.
+
+```ruby
+class CSP::Constraint
+  def initialize(variables)
+    @variables = variables
+  end
+end
+```
+
+But if you need to add other properties besides the variables, you can override the constructor:
+
+```ruby
+# Instead of only purple, now we can choose which color to exclude.
+class MyCustomConstraint < CSP::Constraint
+  def initialize(letters:, color:)
+    # set letters as the variables
+    super(letters)
+
+    @letters = letters
+    @color = color
+  end
+
+  def satisfies?(assignment = {})
+    # since letters is the same as variables, we can usem them interchangeably here.
+    return true if @letters.all? { |letter| assignment[letter].present? }
+
+    # we compare with the color set
+    @letters.all? { |letter| assignment[letter] != @color }
+  end
+end
+```
+
+And now we can use as we see fit:
+```ruby
+problem = CSP::Problem.new
+problem.add_variables(%w[A B C], domains: %w[purple red green blue])
+
+a_cant_be_green = MyCustomConstraint.new(letters: %w[A], color: 'green')
+b_cant_be_purple = MyCustomConstraint.new(letters: %w[B], color: 'purple')
+c_cant_be_blue = MyCustomConstraint.new(letters: %w[C], color: 'blue')
+
+problem.add_constraint(a_cant_be_green)
+problem.add_constraint(b_cant_be_purple)
+problem.add_constraint(c_cant_be_blue)
+```
+
+##### **TL;DR**
+* Inherit from `CSP::Constraint`
+* Implement a `satisfies?(assignment = {})` that returns a boolean
+* Override the initializer if needed, but pass to `super` the constraint's variables
+
+### Solving the problem
+After setting the problem we can search for the solution by calling `solve`:
+
+```ruby
+problem.solve
+# => { 'A' => 'green', 'B' => 'red', 'C' => 'purple' }
+```
+
+### Full Example:
+
+```ruby
+# Given the letters A-C, pick a color between red, blue, green, and purple for them.
+# Consider the following rules:
+# * Each letters has a unique color
+# * A can't have the color purple
+# * A and C can't have the color red
+# * B can't have the color purple nor green
+
+# Create a constraint class
+class MyCustomConstraint < CSP::Constraint
+  def initialize(letters:, color:)
+    super(letters)
+    @letters = letters
+    @color = color
+  end
+
+  def satisfies?(assignment = {})
+    @letters.all? { |letter| assignment[letter] != @color }
+  end
+end
+
+# Initialize the problem
+problem = CSP::Problem.new
+
+# Define the letters as variables and colors as domains
+variables = %w[A B C]
+domains = %w[purple red green blue]
+
+# Create constraints using the custom class
+a_cant_be_purple = MyCustomConstraint.new(letters: %w[A], color: 'purple')
+a_and_c_cant_be_red = MyCustomConstraint.new(letters: %w[A C], color: 'red')
+
+# Add variables and domains
+problem.add_variables(variables, domains: domains)
+
+# Set the unique color constraint
+problem.all_different
+
+# set A != purple constraint
+problem.add_constraint(a_cant_be_purple)
+
+# set A != purple && C != purple constraint
+problem.add_constraint(a_and_c_cant_be_red)
+
+# set B != purple && B != green constraint
+problem.add_constraint(variables: %w[B]) { |b| b != 'purple' && b != 'green' }
+
+# find the solution
+problem.solve
+# => { 'A' => 'green', 'B' => 'red', 'C' => 'purple' }
+```
+
+## License
+This project is licensed under the [MIT License](MIT-LICENSE).

data/Rakefile

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+task default: %i[]

data/csp-resolver.gemspec

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative 'lib/csp/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'csp-resolver'
+  spec.version = CSP::VERSION
+  spec.license = 'MIT'
+  spec.authors = ['André Benjamim', 'Gustavo Alberto']
+  spec.email = ['andre.benjamim@rebase.com.br', 'gustavo.costa@rebase.com.br']
+
+  spec.summary = 'A Ruby CSP Solver'
+  spec.description = 'This Ruby gem solves CSPs using custom constraints'
+  spec.homepage = 'https://github.com/Rebase-BR/csp-resolver'
+  spec.required_ruby_version = '>= 2.5.8'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/Rebase-BR/csp-resolver'
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git appveyor Gemfile])
+    end
+  end
+  spec.bindir = 'exe'
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+end

data/examples/event_scheduling.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative '../lib/csp-resolver'
+
+module CSP
+  module Examples
+    class EventScheduling
+      def call
+        number_of_events = 3
+        number_of_time_slots = 4
+
+        variables = number_of_events.times.to_a
+        domains = number_of_time_slots.times.to_a
+
+        csp = CSP::Problem.new
+          .add_variables(variables, domains: domains)
+
+        variables.combination(2).each do |events|
+          add_constraint(csp, *events)
+        end
+
+        solution = csp.solve
+        solution || 'No solution found'
+      end
+
+      def add_constraint(csp, event1, event2)
+        csp.add_constraint(OnlyOneConstraint.new(event1, event2))
+      end
+
+      class OnlyOneConstraint < ::CSP::Constraint
+        attr_reader :event1, :event2
+
+        def initialize(event1, event2)
+          super([event1, event2])
+
+          @event1 = event1
+          @event2 = event2
+        end
+
+        def satisfies?(assignment)
+          return true if variables.any? { |variable| !assignment.key?(variable) }
+
+          assignment[event1] != assignment[event2]
+        end
+      end
+    end
+  end
+end

data/examples/map_coloring.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require_relative '../lib/csp-resolver'
+
+module CSP
+  module Examples
+    class MapColoring
+      def call # rubocop:disable Metrics/MethodLength
+        variables = [
+          'Western Australia',
+          'Northern Territory',
+          'South Australia',
+          'Queensland',
+          'New South Wales',
+          'Victoria',
+          'Tasmania'
+        ]
+
+        domains = %w[red blue green]
+
+        csp = CSP::Problem.new
+          .add_variables(variables, domains: domains)
+
+        add_constraint(csp, 'Western Australia', 'Northern Territory')
+        add_constraint(csp, 'Western Australia', 'South Australia')
+        add_constraint(csp, 'South Australia', 'Northern Territory')
+        add_constraint(csp, 'Queensland', 'Northern Territory')
+        add_constraint(csp, 'Queensland', 'South Australia')
+        add_constraint(csp, 'Queensland', 'New South Wales')
+        add_constraint(csp, 'New South Wales', 'South Australia')
+        add_constraint(csp, 'Victoria', 'South Australia')
+        add_constraint(csp, 'Victoria', 'New South Wales')
+        add_constraint(csp, 'Victoria', 'Tasmania')
+
+        solution = csp.solve
+        solution || 'No solution found'
+      end
+
+      def add_constraint(csp, place1, place2)
+        csp.add_constraint(MapColoringConstraint.new(place1, place2))
+      end
+
+      class MapColoringConstraint < ::CSP::Constraint
+        attr_reader :place1, :place2
+
+        def initialize(place1, place2)
+          super([place1, place2])
+
+          @place1 = place1
+          @place2 = place2
+        end
+
+        def satisfies?(assignment)
+          # If any of them is not assigned then there's no conflict
+          return true if variables.any? { |variable| !assignment.key?(variable) }
+
+          assignment[place1] != assignment[place2]
+        end
+      end
+    end
+  end
+end

data/examples/queen.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative '../lib/csp-resolver'
+
+module CSP
+  module Examples
+    class Queen
+      def call(queens_number = 8)
+        variables = queens_number.times.to_a
+
+        csp = CSP::Problem.new
+          .add_variables(variables, domains: variables)
+          .add_constraint(QueensConstraint.new(variables))
+        solution = csp.solve
+
+        solution || 'No solution found'
+      end
+
+      class QueensConstraint < ::CSP::Constraint
+        attr_reader :columns
+
+        def initialize(columns)
+          super(columns)
+
+          @columns = columns
+        end
+
+        def satisfies?(assignment)
+          assignment.each do |(queen_col1, queen_row1)|
+            (queen_col1 + 1..columns.size).each do |queen_col2|
+              next unless assignment.key?(queen_col2)
+
+              queen_row2 = assignment[queen_col2]
+
+              return false if queen_row1 == queen_row2
+              return false if (queen_row1 - queen_row2).abs == (queen_col1 - queen_col2).abs
+            end
+          end
+
+          true
+        end
+      end
+    end
+  end
+end

data/examples/sculpture.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative '../lib/csp-resolver'
+
+module CSP
+  module Examples
+    # Three sculptures (A, B, C) are to be exhibited in rooms 1,2 of an art gallery
+    #
+    # The exhibition must satisfy the following conditions:
+    # 1. Sculptures A and B cannot be in the same room
+    # 2. Sculptures B and C must be in the same room
+    # 3. Room 2 can only hold one sculpture
+    class Sculpture
+      def call
+        variables = %w[A B C]
+
+        csp = CSP::Problem.new
+          .add_variable('A', domains: [1, 2])
+          .add_variable('B', domains: [1, 2])
+          .add_variable('C', domains: [1, 2])
+          .unique(%w[A B])
+          .add_constraint(variables: %w[B C]) { |b, c| b == c }
+          .add_constraint(RoomLimitToOneConstraint.new(room: 2, variables: variables))
+        solution = csp.solve
+
+        solution || 'No solution found'
+      end
+
+      class CannotBeInSameRoomConstraint < ::CSP::Constraint
+        def satisfies?(assignment)
+          values = assignment.values_at(*variables)
+
+          return true if values.any?(&:nil?)
+
+          values == values.uniq
+        end
+      end
+
+      class MustBeInSameRoomConstraint < ::CSP::Constraint
+        def satisfies?(assignment)
+          values = assignment.values_at(*variables)
+
+          return true if values.any?(&:nil?)
+
+          values.uniq.size == 1
+        end
+      end
+
+      class RoomLimitToOneConstraint < ::CSP::Constraint
+        attr_reader :room
+
+        def initialize(room:, variables:)
+          super(variables)
+          @room = room
+        end
+
+        def satisfies?(assignment)
+          values = assignment.values_at(*variables)
+
+          values.count(room) <= 1
+        end
+      end
+    end
+  end
+end

data/lib/csp/algorithms/backtracking.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+
+module CSP
+  module Algorithms
+    class Backtracking
+      extend Forwardable
+
+      ORDERING_ALGORITHM = Ordering::NoOrder
+      FILTERING_ALGORITHM = Filtering::NoFilter
+      LOOKAHEAD_ALGORITHM = Lookahead::NoAlgorithm
+
+      attr_reader :problem, :solutions, :max_solutions,
+                  :ordering_algorithm, :filtering_algorithm, :lookahead_algorithm
+
+      def_delegators :problem, :variables, :constraints
+
+      def initialize(
+        problem:,
+        ordering_algorithm: nil,
+        filtering_algorithm: nil,
+        lookahead_algorithm: nil,
+        max_solutions: 1
+      )
+        @problem = problem
+        @ordering_algorithm = ordering_algorithm || ORDERING_ALGORITHM.new(problem)
+        @filtering_algorithm = filtering_algorithm || FILTERING_ALGORITHM.new(problem)
+        @lookahead_algorithm = lookahead_algorithm || LOOKAHEAD_ALGORITHM.new(problem)
+        @max_solutions = max_solutions
+        @solutions = []
+      end
+
+      def backtracking(assignment = {})
+        backtracking_recursion(assignment, problem_domains)
+      end
+
+      def consistent?(variable, assignment)
+        constraints[variable].all? do |constraint|
+          constraint.satisfies?(assignment)
+        end
+      end
+
+      private
+
+      def problem_domains
+        problem.domains
+      end
+
+      def backtracking_recursion(assignment, domains)
+        return solutions if max_solutions?
+        return add_solution(assignment) if complete?(assignment)
+
+        unassigned = next_unassigned_variable(assignment)
+
+        domains_for(unassigned, assignment, domains).each do |value|
+          local_assignment = assignment.clone
+          local_assignment[unassigned] = value
+
+          next unless consistent?(unassigned, local_assignment)
+
+          new_domains = lookahead(local_assignment, domains)
+
+          next unless new_domains
+
+          backtracking_recursion(local_assignment, new_domains)
+
+          return solutions if max_solutions?
+        end
+
+        []
+      end
+
+      def add_solution(assignment)
+        solutions << assignment
+      end
+
+      def max_solutions?
+        solutions.size >= max_solutions
+      end
+
+      def complete?(assignment)
+        assignment.size == variables.size
+      end
+
+      def next_unassigned_variable(assignment)
+        unassigned_variables(assignment).first
+      end
+
+      def unassigned_variables(assignment)
+        variables
+          .reject { |variable| assignment.key?(variable) }
+          .yield_self { |v| ordering_algorithm.call(v) }
+      end
+
+      def domains_for(unassigned, assignment, domains)
+        filtering_algorithm.call(
+          values: domains[unassigned],
+          assignment_values: assignment.values.flatten
+        )
+      end
+
+      def lookahead(assignment, domains)
+        lookahead_algorithm.call(
+          variables: variables,
+          assignment: assignment,
+          domains: domains
+        )
+      end
+    end
+  end
+end

data/lib/csp/algorithms/filtering/no_filter.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module CSP
+  module Algorithms
+    module Filtering
+      class NoFilter
+        attr_reader :problem
+
+        def self.for(problem:, dependency: nil) # rubocop:disable Lint/UnusedMethodArgument
+          new(problem)
+        end
+
+        def initialize(problem)
+          @problem = problem
+        end
+
+        def call(values:, assignment_values: []) # rubocop:disable Lint/UnusedMethodArgument
+          values
+        end
+      end
+    end
+  end
+end

data/lib/csp/algorithms/lookahead/ac3.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module CSP
+  module Algorithms
+    module Lookahead
+      class Ac3
+        attr_reader :problem
+
+        def initialize(problem)
+          @problem = problem
+        end
+
+        def call(variables:, assignment:, domains:)
+          new_domains = variables.each_with_object({}) do |variable, domains_hash|
+            variable_domains = Array(assignment[variable] || domains[variable])
+
+            domains_hash[variable] = unary_check(variable, variable_domains)
+          end
+
+          variable_arcs = arcs(variables)
+
+          arc_consistency(variable_arcs, new_domains)
+        end
+
+        def arc_consistency(arcs, domains)
+          queue = arcs.dup
+
+          until queue.empty?
+            arc, *queue = queue
+            x, y = arc.keys.first
+            constraint = arc.values.first
+
+            next unless arc_reduce(x, y, constraint, domains)
+            return nil if domains[x].empty?
+
+            new_arcs = find_arcs(x, y, arcs)
+            queue.push(*new_arcs)
+          end
+
+          domains
+        end
+
+        def arc_reduce(x, y, constraint, domains) # rubocop:disable Naming/MethodParameterName
+          changed = false
+          x_domains = domains[x]
+          y_domains = domains[y]
+
+          x_domains.each do |x_value|
+            consistent = y_domains.any? do |y_value|
+              sat = constraint.satisfies?({ x => x_value, y => y_value })
+
+              sat
+            end
+
+            next if consistent
+
+            x_domains -= [x_value]
+            changed = true
+          end
+
+          domains[x] = x_domains
+
+          changed
+        end
+
+        # Returns all (z, x) arcs where z != y
+        def find_arcs(x, y, arcs) # rubocop:disable Naming/MethodParameterName
+          arcs.select do |arc|
+            arc.any? do |(first, second), _constraint|
+              first != y && second == x
+            end
+          end
+        end
+
+        # Setup arcs between variables
+        def arcs(variables)
+          variables.each_with_object([]) do |variable, worklist|
+            constraints = problem.constraints[variable].select(&:binary?)
+
+            constraints.each do |constraint|
+              variables_ij = [variable] | constraint.variables # make current variable be the first
+
+              worklist << { variables_ij => constraint }
+            end
+          end
+        end
+
+        def unary_check(variable, variable_domains)
+          constraints = problem.constraints[variable].select(&:unary?)
+
+          variable_domains.select do |domain|
+            constraints.all? do |constraint|
+              constraint.satisfies?({ variable => domain })
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/csp/algorithms/lookahead/no_algorithm.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module CSP
+  module Algorithms
+    module Lookahead
+      class NoAlgorithm
+        attr_reader :problem
+
+        def initialize(problem)
+          @problem = problem
+        end
+
+        def call(variables:, assignment:, domains:) # rubocop:disable Lint/UnusedMethodArgument
+          domains
+        end
+      end
+    end
+  end
+end

data/lib/csp/algorithms/ordering/no_order.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module CSP
+  module Algorithms
+    module Ordering
+      class NoOrder
+        attr_reader :problem
+
+        def self.for(problem:, dependency: nil) # rubocop:disable Lint/UnusedMethodArgument
+          new(problem)
+        end
+
+        def initialize(problem)
+          @problem = problem
+        end
+
+        def call(variables)
+          variables
+        end
+      end
+    end
+  end
+end

data/lib/csp/constraint.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module CSP
+  class Constraint
+    attr_reader :variables
+
+    def initialize(variables = [])
+      @variables = variables
+    end
+
+    def satisfies?(_assignment = {})
+      raise StandardError, 'Not Implemented. Should return a boolean'
+    end
+
+    def unary?
+      arity == 1
+    end
+
+    def binary?
+      arity == 2
+    end
+
+    def arity
+      @arity ||= variables.size
+    end
+  end
+end

data/lib/csp/constraints.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module CSP
+  module Constraints
+    class AllDifferentConstraint < CSP::Constraint
+      def satisfies?(assignment)
+        assignment.values == assignment.values.uniq
+      end
+    end
+
+    class UniqueConstraint < CSP::Constraint
+      def satisfies?(assignment)
+        values = assignment.values_at(*variables)
+
+        return true if values.any?(&:nil?)
+
+        values == values.uniq
+      end
+    end
+
+    class CustomConstraint < CSP::Constraint
+      attr_reader :block
+
+      def initialize(variables, block)
+        super(variables)
+        @block = block
+      end
+
+      def satisfies?(assignment)
+        values = assignment.values_at(*variables)
+        return true if values.any?(&:nil?)
+
+        block.call(*values)
+      end
+    end
+
+    def all_different
+      add_constraint(AllDifferentConstraint.new(variables))
+
+      self
+    end
+
+    def unique(variables)
+      add_constraint(UniqueConstraint.new(variables))
+
+      self
+    end
+  end
+end

data/lib/csp/problem.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module CSP
+  # TODO: implement dependent factor with weight
+  # TODO: implement lookahead, arc-consistency, ac3
+  class Problem
+    include CSP::Constraints
+
+    attr_reader :variables, :domains, :constraints, :max_solutions,
+                :ordering_algorithm, :filtering_algorithm, :lookahead_algorithm
+
+    InvalidConstraintVariable = Class.new(StandardError)
+    VariableShouldNotBeEmpty = Class.new(StandardError)
+    DomainsShouldNotBeEmpty = Class.new(StandardError)
+    VariableAlreadySeted = Class.new(StandardError)
+
+    def initialize(max_solutions: 1)
+      @variables = []
+      @domains = {}
+      @constraints = {}
+      @max_solutions = max_solutions
+    end
+
+    def solve(assignment = {})
+      Utils::Array.wrap(search_solution(assignment))
+    end
+
+    def add_variable(variable, domains:)
+      if (variable.respond_to?(:empty?) && variable.empty?) || variable.nil?
+        raise VariableShouldNotBeEmpty, 'Variable was empty in the function parameter'
+      end
+      raise DomainsShouldNotBeEmpty, 'Domains was empty in the function parameter' if domains.empty?
+      raise VariableAlreadySeted, "Variable #{variable} has already been seted" if variables.include?(variable)
+
+      variables << variable
+      @domains[variable] = domains
+      constraints[variable] = []
+
+      self
+    end
+
+    def add_variables(variables, domains:)
+      variables.each do |variable|
+        add_variable(variable, domains: domains)
+      end
+
+      self
+    end
+
+    def add_constraint(constraint = nil, variables: nil, &block)
+      validate_parameters(constraint, variables, block)
+
+      constraint = CustomConstraint.new(variables, block) if block
+
+      constraint.variables.each do |variable|
+        next constraints[variable] << constraint if constraints.include?(variable)
+
+        raise InvalidConstraintVariable,
+              "Constraint's variable doesn't exists in CSP"
+      end
+
+      self
+    end
+
+    def add_ordering(ordering_algorithm)
+      @ordering_algorithm = ordering_algorithm
+    end
+
+    def add_filtering(filtering_algorithm)
+      @filtering_algorithm = filtering_algorithm
+    end
+
+    def add_lookahead(lookahead_algorithm)
+      @lookahead_algorithm = lookahead_algorithm
+    end
+
+    private
+
+    def validate_parameters(constraint, variables, block)
+      if missing_both_constraint_and_block?(constraint, block)
+        raise ArgumentError, 'Either constraint or block must be provided'
+      end
+      if provided_both_constraint_and_block?(constraint, block)
+        raise ArgumentError, 'Both constraint and block cannot be provided at the same time'
+      end
+      if missing_variables_for_block?(block, variables)
+        raise ArgumentError, 'Variables must be provided when using a block'
+      end
+      return unless block_arity_exceeds_variables?(block, variables)
+
+      raise ArgumentError, 'Block should not have more arity than the quantity of variables'
+    end
+
+    def missing_both_constraint_and_block?(constraint, block)
+      constraint.nil? && block.nil?
+    end
+
+    def provided_both_constraint_and_block?(constraint, block)
+      constraint && block
+    end
+
+    def missing_variables_for_block?(block, variables)
+      block && variables.nil?
+    end
+
+    def block_arity_exceeds_variables?(block, variables)
+      !variables.nil? && block.arity > variables.length
+    end
+
+    def search_solution(assignment = {})
+      algorithm.backtracking(assignment)
+    end
+
+    def algorithm
+      Algorithms::Backtracking.new(
+        problem: self,
+        ordering_algorithm: ordering_algorithm,
+        filtering_algorithm: filtering_algorithm,
+        lookahead_algorithm: lookahead_algorithm,
+        max_solutions: max_solutions
+      )
+    end
+  end
+end

data/lib/csp/utils.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Utils
+  module Array
+    def self.wrap(object)
+      if object.nil?
+        []
+      elsif object.respond_to?(:to_ary)
+        object.to_ary || [object]
+      else
+        [object]
+      end
+    end
+  end
+end

data/lib/csp/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module CSP
+  VERSION = '0.0.1'
+end

data/lib/csp-resolver.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative 'csp/version'
+require_relative 'csp/constraint'
+require_relative 'csp/utils'
+require_relative 'csp/algorithms/filtering/no_filter'
+require_relative 'csp/algorithms/ordering/no_order'
+require_relative 'csp/algorithms/lookahead/no_algorithm'
+require_relative 'csp/algorithms/lookahead/ac3'
+require_relative 'csp/algorithms/backtracking'
+require_relative 'csp/constraints'
+require_relative 'csp/problem'
+
+module CSP; end

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification
+name: csp-resolver
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- André Benjamim
+- Gustavo Alberto
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2024-05-16 00:00:00.000000000 Z
+dependencies: []
+description: This Ruby gem solves CSPs using custom constraints
+email:
+- andre.benjamim@rebase.com.br
+- gustavo.costa@rebase.com.br
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- MIT-LICENSE
+- README.md
+- Rakefile
+- csp-resolver.gemspec
+- examples/event_scheduling.rb
+- examples/map_coloring.rb
+- examples/queen.rb
+- examples/sculpture.rb
+- lib/csp-resolver.rb
+- lib/csp/algorithms/backtracking.rb
+- lib/csp/algorithms/filtering/no_filter.rb
+- lib/csp/algorithms/lookahead/ac3.rb
+- lib/csp/algorithms/lookahead/no_algorithm.rb
+- lib/csp/algorithms/ordering/no_order.rb
+- lib/csp/constraint.rb
+- lib/csp/constraints.rb
+- lib/csp/problem.rb
+- lib/csp/utils.rb
+- lib/csp/version.rb
+homepage: https://github.com/Rebase-BR/csp-resolver
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/Rebase-BR/csp-resolver
+  source_code_uri: https://github.com/Rebase-BR/csp-resolver
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.5.8
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: A Ruby CSP Solver
+test_files: []