ripple-down-rules 0.6.47__tar.gz → 0.6.49__tar.gz

{ripple_down_rules-0.6.47 → ripple_down_rules-0.6.49}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ripple_down_rules
-Version: 0.6.47
+Version: 0.6.49
 Summary: Implements the various versions of Ripple Down Rules (RDR) for knowledge representation and reasoning.
 Author-email: Abdelrhman Bassiouny <abassiou@uni-bremen.de>
 License:                     GNU GENERAL PUBLIC LICENSE

ripple_down_rules-0.6.49/doc/_toc.yml

@@ -0,0 +1,12 @@
+# Table of contents
+# Learn more at https://jupyterbook.org/customize/toc.html
+
+format: jb-book
+root: intro
+chapters:
+- file: relational_example_tutorial
+- file: relational_example_with_decorator_tutorial
+- file: test_driven_rdr_fitting_tutorial
+- file: propositional_example_tutorial
+- file: bibliography
+- file: autoapi/index

ripple_down_rules-0.6.49/doc/intro.md

@@ -0,0 +1,150 @@
+# Ripple Down Rules
+
+
+Welcome to the Ripple Down Rules package!
+The ripple_down_rules is a python package that implements the various ripple down rules versions, including 
+Single Classification (SCRDR), Multi Classification (MCRDR), and Generalised Ripple Down Rules (GRDR).
+
+SCRDR, MCRDR, and GRDR are rule-based classifiers that are built incrementally, and can be used to classify data cases.
+The rules are refined as new data cases are classified, this is done by prompting the user to add a new rule when a case
+is misclassified or not classified at all. This allows the system to adapt to new data without the need for retraining.
+
+SCRDR, MCRDR, and GRDR logic were inspired from the book: 
+["Ripple Down Rules: An Alternative to Machine Learning"](https://www.taylorfrancis.com/books/mono/10.1201/9781003126157/ripple-rules-paul-compton-byeong-ho-kang) by Paul Compton, Byeong Ho Kang.
+
+
+## 🚀 Enhanced Ripple-Down Rules Engine – Key Features
+
+### 🧠 Data Model (Ontology) + Rule Base as One Entity
+- 🧬 Unified data structure: Data Model (Ontology) and rules use the same Python data structures. 
+- 🔄 Automatic sync: Updates to the data model instantly reflect in the rule base. 
+- 📦 Version controlled: The rule base is a Python module, versioned with your project.
+
+### 🔁 Supports First, Second & Higher-Order Logic
+- 🧩 Unlimited expressiveness: Rule conditions and conclusions are plain Python functions — anything Python can do, your rules can too!
+
+### 🛡️ Automatic Rule Base Maintenance 
+- ⚠️ Contradiction detection: New rules are auto-checked for logical conflicts. 
+- 🔧 Prompted refinements: If a contradiction arises, you're guided to add a refinement rule. 
+
+### 📝 Transparent & Editable Rule Base
+- 📖 Readable rules: Rules are clean, understandable Python code. 
+- 🔄 Reload-friendly: Easily edit and reload rules manually as needed.
+
+### 💻 Developer-Centric Interface
+- 👨‍💻 Feels like home: Seamless integration with your favorite IDE.
+- ✨ Modern coding experience: Auto-completion and suggestions supported via IDE plugins.
+
+### 🤖 LLM-Powered Rule Writing
+- 💡 AI-assisted authoring: Ask AI for help or suggestions directly within the IDE.
+- ⚡ Smart completion: Context-aware completions streamline rule writing.
+
+### 🎯 Flexible Rule Specificity
+- 🧪 Instance-level precision: Write rules for highly specific object scenarios.
+- 🏛️ Generalization-ready: Create broad rules for superclass relationships.
+
+### 🖼️ GUI for Rule Exploration
+- 🧭 Object Explorer Panel: Navigate and inspect objects easily.
+- 🧯 Interactive Diagram: Expandable/collapsible object diagram to guide rule creation visually.
+
+This work aims to provide a flexible and powerful rule-based system that can be used in various applications,
+from simple classification tasks to complex decision-making systems. Furthermore, one of the main goals is to
+provide an easy-to-use interface that allows users to write rules in a natural way, without the need for
+complex configurations or setups, and without the need to learn old or deprecated programming languages.
+
+Future (and current) work will focus on improving the user experience, adding more features, and enhancing the
+performance, so stay tuned for updates! and feel free to contribute, give feedback, or report issues on the
+[GitHub repository](https://github.com/AbdelrhmanBassiouny/ripple_down_rules/issues)
+
+## To Cite:
+
+```bib
+@software{bassiouny2025rdr,
+author = {Bassiouny, Abdelrhman},
+title = {Ripple-Down-Rules},
+url = {https://github.com/AbdelrhmanBassiouny/ripple_down_rules},
+version = {0.6.47},
+}
+```
+
+## Installation
+```bash
+sudo apt-get install graphviz graphviz-dev
+pip install ripple_down_rules
+```
+For GUI support, also install:
+
+```bash
+sudo apt-get install libxcb-cursor-dev
+```
+
+## Technical Overview
+
+### CaseQuery
+
+The {py:class}`ripple_down_rules.datastructures.dataclasses.CaseQuery` class is a data structure that represents a query for a case in the ripple down rules system.
+It mainly requires the queried object which is referred to as `case`, the target attribute that is being queried, the type(s) of the target, and a boolean indicating whether the target is mutually exclusive or not.
+
+### RippleDownRules
+
+{py:class}`ripple_down_rules.rdr.RippleDownRules` This is the main abstract class for the ripple down rules. From this class, the different versions of
+ripple down rules are derived. So the {py:class}`ripple_down_rules.rdr.SingleClassRDR`, {py:class}`ripple_down_rules.rdr.MultiClassRDR`, and {py:class}`ripple_down_rules.rdr.GeneralRDR` classes
+are all derived from this class.
+
+For most cases, you will use the `GeneralRDR` class, which is the most general version of the ripple down rules, 
+and it internally uses the `SingleClassRDR` and `MultiClassRDR` classes to handle the classification tasks depending
+on the case query.
+
+This class has four main methods that you will mostly use:
+
+- {py:func}`ripple_down_rules.rdr.RippleDownRules.fit`: This method is used to fit the rules to the data. It takes a list of `CaseQuery` objects that contain the
+  data cases and their targets, and it will prompt the user to add rules when a case is misclassified or not classified at all.
+- {py:func}`ripple_down_rules.rdr.RippleDownRules.fit_case`: This method is used to fit a single case to the rules.
+- {py:func}`ripple_down_rules.rdr.RippleDownRules.classify`: This method is used to classify a data case. It takes a data case (any python object) and returns the
+predicted target.
+- {py:func}`ripple_down_rules.rdr.RippleDownRules.save`: This method is used to save the rules to a file. It will save the rules as a python module that can be imported
+  in your project. In addition, it will save the rules as a JSON file with some metadata about the rules.
+- {py:func}`ripple_down_rules.rdr.RippleDownRules.load`: This method is used to load the rules from a file. It will load the rules from a JSON file and then update the
+  rules from the python module (which is important in case the user manually edited the rules in the python module).
+
+### SingleClassRDR
+This is the single classification version of the ripple down rules. It is used to classify data cases into a single
+target class. This is used when your classification is mutually exclusive, meaning that a data case can only belong
+to one class. For example, an animal can be either a "cat" or a "dog", but not both at the same time.
+
+### MultiClassRDR
+This is the multi classification version of the ripple down rules. It is used to classify data cases into multiple
+target classes. This is used when your classification is not mutually exclusive, meaning that a data case can belong
+to multiple classes at the same time. For example, an animal's habitat can be both "land" and "water" at the same time.
+
+### GeneralRDR
+This is the general version of the ripple down rules. It has the following features:
+- It can handle both single and multi classification tasks by creating instances of `SingleClassRDR` and `MultiClassRDR`
+  internally depending on the case query.
+- It performs multiple passes over the rules and uses conclusions from previous passes to refine the classification,
+    which allows it to handle complex classification tasks.
+
+## Expert
+
+The {py:class}`ripple_down_rules.experts.Expert` is an interface between the ripple down rules and the rule writer. Currently, only a {py:class}`ripple_down_rules.experts.Human` expert is
+implemented, but it is designed to be easily extendable to other types of experts, such as LLMs or other AI systems.
+
+The main APIs are:
+
+- {py:func}`ripple_down_rules.experts.Expert.ask_for_conclusion`: This method is used to ask the expert for a conclusion or a target for a data case.
+- {py:func}`ripple_down_rules.experts.Expert.ask_for_conditions`: This method is used to ask the expert for the conditions that should be met for a rule to be
+applied or evaluated.
+
+## RDRDecorator
+
+The {py:class}`ripple_down_rules.rdr_decorators.RDRDecorator` is a decorator that can be used to create rules in a more convenient way. It allows you to write 
+functions normally and then decorate them with the `@RDRDecorator().decorator`. This will allow the function to be
+to use ripple down rules to provide its output. This also allows you to write your own initial function logic, and then
+this will be used input or feature to the ripple down rules.
+
+
+## Example Usage
+
+- [Relational Example](relational_example_tutorial.md): This example shows how to use the Ripple Down Rules to classify objects in a relational model.
+- [Relational Example with Decorator](relational_example_with_decorator_tutorial.md): This example shows how to use the Ripple Down Rules with a decorator to overload methods.
+- [Propositional Example](propositional_example_tutorial.md): This example shows generic usage of the Ripple Down Rules to classify objects in a propositional setting.

ripple_down_rules-0.6.49/doc/propositional_example_tutorial.md

@@ -0,0 +1,114 @@
+### Propositional Example Tutorial
+
+By propositional, I mean that each rule conclusion is a propositional logic statement with a constant value.
+
+For this example, we will use the [UCI Zoo dataset](https://archive.ics.uci.edu/ml/datasets/zoo) to classify animals
+into their species based on their features. The dataset contains 101 animals with 16 features, and the target is th
+e species of the animal.
+
+To install the dataset:
+```bash
+pip install ucimlrepo
+```
+
+### Prepare the Data
+
+Put this in a file named `propositional_data.py`:
+
+```python
+from __future__ import annotations
+from ripple_down_rules.datastructures.case import create_cases_from_dataframe
+from ucimlrepo import fetch_ucirepo
+from enum import Enum
+
+class Species(str, Enum):
+    """Enum for the species of the animals in the UCI Zoo dataset."""
+    mammal = "mammal"
+    bird = "bird"
+    reptile = "reptile"
+    fish = "fish"
+    amphibian = "amphibian"
+    insect = "insect"
+    molusc = "molusc"
+    
+    @classmethod
+    def from_str(cls, value: str) -> Species:
+        return getattr(cls, value)
+
+# fetch dataset
+zoo = fetch_ucirepo(id=111)
+
+# data (as pandas dataframes)
+X = zoo.data.features
+y = zoo.data.targets
+
+# This is a utility that allows each row to be a Case instance,
+# which simplifies access to column values using dot notation.
+all_cases = create_cases_from_dataframe(X, name="Animal")
+
+# The targets are the species of the animals
+category_names = ["mammal", "bird", "reptile", "fish", "amphibian", "insect", "molusc"]
+category_id_to_name = {i + 1: name for i, name in enumerate(category_names)}
+targets = [Species.from_str(category_id_to_name[i]) for i in y.values.flatten()]
+```
+
+### Define the Case Queries
+Create a new python script to define the case queries and the Ripple Down Rules classifier.
+For every target, we create a `CaseQuery` that specifies the case, the target attribute, the type of the target,
+and whether the classification is mutually exclusive or not. In this case, we set `mutually_exclusive` to `True` since
+each animal belongs to only one species.
+```python
+from ripple_down_rules import CaseQuery
+from propositional_data import all_cases, targets, Species
+
+
+case_queries = [CaseQuery(case, 'species', type(target), True, _target=target)
+                for case, target in zip(all_cases[:10], targets[:10])]
+```
+
+### Create and Use the Ripple Down Rules Classifier
+
+```python
+# Optionally Enable GUI if available
+from ripple_down_rules.helpers import enable_gui
+enable_gui()
+
+
+from ripple_down_rules import GeneralRDR
+from ripple_down_rules.utils import render_tree
+
+
+# Now that we are done with the data preparation, we can create and use the Ripple Down Rules classifier.
+grdr = GeneralRDR(save_dir="./", model_name="species_rdr")
+
+# Fit the GRDR to the data
+grdr.fit(case_queries, animate_tree=True)
+
+# Render the tree to a file
+render_tree(grdr.start_rules[0], use_dot_exporter=True, filename="species_rdr")
+
+# Classify a case
+cat = grdr.classify(all_cases[50])
+assert cat['species'] == targets[50]
+```
+
+When prompted to write conditions for the given target, I press the "Edit" buttond (%edit in the Ipython interface) and I wrote the following
+inside the template function that the Ripple Down Rules created:
+```python
+return case.milk == 1
+```
+Then, I press the "Load" button (%load in Ipython), this loads the function I just wrote such that I can test it inside
+the Ipython interface.
+After that, I press the "Accept" button (return func_name(case) in Ipython), this will save the rule permanently.
+
+When prompted for conditions for the next target, I wrote the following inside the template function that the
+Ripple Down Rules created:
+```python
+return case.aquatic == 1
+```
+
+I keep doing this for all the prompts until I have fitted the rules such that the classifier correctly classifies the
+animals in the dataset. This took around 10 prompts in total, and the rules correctly classified 101 animals in the dataset.
+
+The rule tree generated from fitting all the dataset will look like this:
+![species_rdr](https://raw.githubusercontent.com/AbdelrhmanBassiouny/ripple_down_rules/main/images/scrdr.png)

ripple_down_rules-0.6.49/doc/relational_example_tutorial.md

@@ -0,0 +1,120 @@
+# Relational Example Tutorial
+
+In this tutorial, we will walk through the process of fitting a Ripple Down Rules (RDR) model to a relational data model.
+Where there are multiple objects that are related to each other, and we want to query them using Ripple Down Rules.
+
+<iframe width="560" height="315" src="https://www.youtube.com/embed/Dgcj7Y7qNyI" frameborder="0" allowfullscreen></iframe>
+
+### Define your Data Model
+
+Here we define a simple data model of a robot with parts both of which are physical objects and can contain other physical objects.
+Put this in a file called `relational_model.py`:
+```python
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing_extensions import List
+
+
+@dataclass(unsafe_hash=True)
+class PhysicalObject:
+    """
+    A physical object is an object that can be contained in a container.
+    """
+    name: str
+    contained_objects: List[PhysicalObject] = field(default_factory=list, hash=False)
+
+@dataclass(unsafe_hash=True)
+class Part(PhysicalObject):
+    ...
+
+@dataclass(unsafe_hash=True)
+class Robot(PhysicalObject):
+    parts: List[Part] = field(default_factory=list, hash=False)
+```
+
+### Create your Case Object (Object to be Queried):
+In a new python script, create instances of the `Part` and `Robot` classes to represent your robot and its parts.
+This will be the object that you will query with Ripple Down Rules.
+```python
+from relational_model import Part, Robot, PhysicalObject
+
+
+part_a = Part(name="A")
+part_b = Part(name="B")
+part_c = Part(name="C")
+robot = Robot("pr2", parts=[part_a])
+part_a.contained_objects = [part_b]
+part_b.contained_objects = [part_c]
+```
+
+### (Optional) Enable Ripple Down Rules GUI
+
+If you want to use the GUI for Ripple Down Rules, ensure you have PyQt6 installed:
+```bash
+pip install pyqt6
+sudo apt-get install libxcb-cursor-dev
+```
+
+Then, you can enable the GUI in your script as follows:
+```python
+# Optionally Enable GUI if available
+from ripple_down_rules.helpers import enable_gui
+enable_gui()
+```
+
+### Define the RDR Model and the Case Query
+Here create/load our RDR model, then we define a query on the `robot` object to find out which objects are contained within it.
+The output type is specified as `PhysicalObject`, and there can be multiple contained objects so we set `mutually_exclusive` to `False`.
+
+Optionally enable the GUI.
+
+```python
+from ripple_down_rules import CaseQuery, GeneralRDR
+
+grdr = GeneralRDR(save_dir='./', model_name='part_containment_rdr')
+
+case_query = CaseQuery(robot, "contained_objects", (PhysicalObject,), False)
+```
+
+### Fit the Model to the Case Query by Answering the prompts.
+```python
+grdr.fit_case(case_query)
+```
+
+When prompted to write a rule, I press edit in GUI (or type %edit in the Ipython interface if not using GUI),
+I wrote the following inside the template function that the Ripple Down Rules created for me, this function takes a
+`case` object as input:
+
+```python
+contained_objects = []
+for part in case.parts:
+    contained_objects.extend(part.contained_objects)
+return contained_objects
+```
+
+I press the "Load" button (%load in Ipython), this loads the function I just wrote such that I can test it inside the
+Ipython interface.
+
+If I like the result, I press the "Accept" button (return func_name(case) in Ipython), this will save the rule
+permanently.
+
+And then when asked for conditions, I wrote the following inside the template function that the Ripple Down Rules
+created:
+
+```python
+return len(case.parts) > 0
+```
+
+This means that the rule will only be applied if the robot has parts.
+
+### Finally, Classify the Object and Verify the Result
+
+```python
+result = grdr.classify(robot)
+assert result['contained_objects'] == {part_b}
+```
+
+If you notice, the result only contains part B, while one could say that part C is also contained in the robot, but,
+the rule we wrote only returns the contained objects of the parts of the robot. To get part C, we would have to
+add another rule that says that the contained objects of my contained objects are also contained in me, you can 
+try that yourself and see if it works!

ripple_down_rules-0.6.49/doc/relational_example_with_decorator_tutorial.md

@@ -0,0 +1,123 @@
+# Relational Example With Decorator Tutorial
+
+Similar to the [Relational Example Tutorial](relational_example_tutorial.md), but using the `RDRDecorator` to enable
+Ripple Down Rules classification on a method of a class (or any method).
+
+<iframe width="560" height="315" src="https://www.youtube.com/embed/iapEdQRZTKo" frameborder="0" allowfullscreen></iframe>
+
+### Define your Data Model With RDRDecorator
+
+Here we define a simple data model of a robot with parts both of which are physical objects and can contain other physical objects.
+We also add an RDRDecorator to the Robot class on the get_contained_objects method to enable Ripple Down Rules classification on this method.
+
+Put this in a file called `relational_model.py`:
+```python
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing_extensions import List
+from ripple_down_rules.rdr_decorators import RDRDecorator
+
+
+@dataclass(unsafe_hash=True)
+class PhysicalObject:
+    """
+    A physical object is an object that can be contained in a container.
+    """
+    name: str
+    contained_objects: List[PhysicalObject] = field(default_factory=list, hash=False)
+
+@dataclass(unsafe_hash=True)
+class Part(PhysicalObject):
+    ...
+
+@dataclass(unsafe_hash=True)
+class Robot(PhysicalObject):
+    parts: List[Part] = field(default_factory=list, hash=False)
+    containment_rdr: RDRDecorator = RDRDecorator("./", (PhysicalObject,), False,
+                                                 fit=False)
+
+    @containment_rdr.decorator
+    def get_contained_objects(self) -> List[PhysicalObject]:
+        """
+        Returns the contained objects of the robot.
+        """
+        ...
+```
+
+### Create your Case Object (Object to be Queried):
+In a new python script, create instances of the `Part` and `Robot` classes to represent your robot and its parts.
+This will be the object that you will query with Ripple Down Rules.
+```python
+from relational_model import Part, Robot, PhysicalObject
+
+
+part_a = Part(name="A")
+part_b = Part(name="B")
+part_c = Part(name="C")
+robot = Robot("pr2", parts=[part_a])
+part_a.contained_objects = [part_b]
+part_b.contained_objects = [part_c]
+```
+
+### (Optional) Enable Ripple Down Rules GUI
+
+If you want to use the GUI for Ripple Down Rules, ensure you have PyQt6 installed:
+```bash
+pip install pyqt6
+sudo apt-get install libxcb-cursor-dev
+```
+
+Then, you can enable the GUI in your script as follows:
+```python
+# Optionally Enable GUI if available
+from ripple_down_rules.helpers import enable_gui
+enable_gui()
+```
+
+### Directly Use the decorated method to Fit/Classify the Object
+```python
+robot.containment_rdr.fit = True
+robot.get_contained_objects()
+
+robot.containment_rdr.fit = False
+contained_objects = robot.get_contained_objects()
+assert contained_objects == [part_b]
+```
+
+When prompted to write a rule, I press edit in GUI (or type %edit in the Ipython interface if not using GUI),
+I wrote the following inside the template function that the Ripple Down Rules created for me, this function takes a
+`case` object as input:
+
+```python
+contained_objects = []
+for part in self_.parts:
+    contained_objects.extend(part.contained_objects)
+return contained_objects
+```
+
+I press the "Load" button (%load in Ipython), this loads the function I just wrote such that I can test it inside the
+Ipython interface.
+
+If I like the result, I press the "Accept" button (return func_name(**case) in Ipython), this will save the rule
+permanently.
+
+And then when asked for conditions, I wrote the following inside the template function that the Ripple Down Rules
+created:
+
+```python
+return len(case.parts) > 0
+```
+
+This means that the rule will only be applied if the robot has parts.
+
+### Additional Tip for RDRDecorator Usage:
+We can let the fit mode be `True`, but give the rdr a function that tells it when to prompt for an answer.
+For example, we can ask for an answer only when the robot's name is "tracy", which will result in the rdr not asking 
+for an answer because the robot name is "pr2" for the current case.
+The input to the `ask_now` function is a dictionary with the original function arguments, while arguments like
+`self` and `cls` are passed as a special key `'self_'` or `'cls_'` respectively.
+```python
+robot.containment_rdr.fit = True
+robot.containment_rdr.ask_now = lambda case: case['self_'].name == "tracy"
+robot.get_contained_objects()
+```

ripple_down_rules-0.6.49/doc/test_driven_rdr_fitting_tutorial.md

@@ -0,0 +1,133 @@
+# Test Driven RDR Fitting Tutorial
+
+In this tutorial, we will walk through the process of fitting a Ripple Down Rules (RDR) model to a case object using a test-driven approach.
+Similar to the [RDR Fitting Tutorial](rdr_fitting_tutorial.md), but with a focus on writing tests first and then
+implementing the rules, this will enable maintenance of the rules and ensure that they work as expected with changes over time,
+and it will enable collaboration with other developers who can write tests for their rules and merge them into the main rule tree.
+
+<iframe width="560" height="315" src="https://www.youtube.com/embed/g5lpQIHYIG0" frameborder="0" allowfullscreen></iframe>
+
+### Define your Data Model
+
+Here we define a simple data model of a robot with parts both of which are physical objects and can contain other physical objects.
+Put this in a file called `relational_model.py`:
+```python
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing_extensions import List
+
+
+@dataclass(unsafe_hash=True)
+class PhysicalObject:
+    """
+    A physical object is an object that can be contained in a container.
+    """
+    name: str
+    contained_objects: List[PhysicalObject] = field(default_factory=list, hash=False)
+
+@dataclass(unsafe_hash=True)
+class Part(PhysicalObject):
+    ...
+
+@dataclass(unsafe_hash=True)
+class Robot(PhysicalObject):
+    parts: List[Part] = field(default_factory=list, hash=False)
+```
+
+### Create your Case Object (Object to be Queried) In a Factory Method:
+In a new python test script, create instances of the `Part` and `Robot` classes to represent your robot and its parts.
+This will be the object that you will query with Ripple Down Rules. Put this inside a factory method such that
+the case can be recreated easily and consistently over the lifetime of the project.
+
+```python
+from relational_model import Part, Robot, PhysicalObject
+from ripple_down_rules import CaseQuery
+
+def robot_factory() -> Robot:
+    """
+    Factory method to create a robot with parts.
+    """
+    part_a = Part(name="A")
+    part_b = Part(name="B")
+    part_c = Part(name="C")
+    
+    robot = Robot("pr2", parts=[part_a])
+    
+    # Establish containment relationships
+    part_a.contained_objects = [part_b]
+    part_b.contained_objects = [part_c]
+    
+    return robot
+```
+
+### Put The RDR model in a pytest fixture (or a normal method):
+Here since this RDR model will most likely be used in multiple tests, we put it in a pytest fixture.
+
+```python
+import pytest
+from ripple_down_rules import GeneralRDR
+
+
+@pytest.fixture
+def robot_rdr():
+    """
+    Fixture to create a GeneralRDR instance for testing.
+    """
+    return GeneralRDR(save_dir='./', model_name='robot_rdr')
+```
+
+### Write a Test for fitting contained_objects of the robot:
+Here we write a test that will check if the `contained_objects` of the robot are correctly identified, and this will also
+serve as the fitting process for the Ripple Down Rules model.
+
+Notice that we added two extra inputs to the `CaseQuery`:
+- `scenario`: This is a reference to the test function itself, which can be useful for debugging and understanding the
+context of the case, and recreating the scenario when verifying the rules or comparing with other rules.
+- `case_factory`: This is a reference to the factory method that creates the case object,
+allowing the RDR model to recreate the case object when needed.
+
+```python
+def test_fit_robot_contained_objects(robot_rdr):
+    """
+    Test to fit the Ripple Down Rules model to the robot's contained objects.
+    """
+    robot = robot_factory()
+    
+    # Define the case query for contained objects
+    case_query = CaseQuery(robot, "contained_objects", (PhysicalObject,), False,
+                           scenario=test_fit_robot_contained_objects,
+                           case_factory=robot_factory)
+    
+    # Fit the RDR model to the case query
+    robot_rdr.fit_case(case_query, update_existing_rules=False)
+    
+    # Classify the object and verify the result
+    result = robot_rdr.classify(robot)
+    
+    # Assert that the result contains part B as the only contained object
+    assert result['contained_objects'] == {robot.parts[0].contained_objects[0]}
+```
+
+### (Optional) Enable Ripple Down Rules GUI
+
+If you want to use the GUI for Ripple Down Rules, ensure you have PyQt6 installed:
+```bash
+pip install pyqt6
+sudo apt-get install libxcb-cursor-dev
+```
+
+Then, you can enable the GUI in your script as follows:
+```python
+# Optionally Enable GUI if available
+from ripple_down_rules.helpers import enable_gui
+enable_gui()
+```
+
+### Run the Test
+
+You can run the test using pytest:
+```bash
+pytest -s test_rdr_fitting.py
+```
+This will execute the test, prompting you to fit the RDR model to the case object or if there is rules already fitted,
+it will classify the object based on the existing rules.

ripple_down_rules-0.6.49/examples/decorator_example.py

@@ -0,0 +1,24 @@
+from decorator_model import Robot
+from relational_model import Part, PhysicalObject
+from ripple_down_rules.helpers import enable_gui
+
+
+# Define a simple robot with parts and containment relationships
+part_a = Part(name="A")
+part_b = Part(name="B")
+part_c = Part(name="C")
+robot = Robot("pr2", parts=[part_a])
+part_a.contained_objects = [part_b]
+part_b.contained_objects = [part_c]
+
+# Optional: Use the GUI.r
+enable_gui()
+
+# Create a GeneralRDR instance and fit it to the case query
+robot.containment_rdr.fit = True
+robot.get_contained_objects()
+
+# Classify the robot to check if it contains part_b
+robot.containment_rdr.fit = False
+result = robot.get_contained_objects()
+assert result == [part_b]