feat: ✨ Port the "volume" mechanism from OpenNARS

A simple "volume" mechanism, ported from OpenNARS, allows the use of cmd `volume` to set values as OpenNARS does and thus limit the production of `OUT` type output.

pynars/ConsolePlus.py

@@ -221,6 +221,19 @@ def toggle_silent() -> None:
         }.''')
 
 
+@cmd_register(('volume'), (int, 100))
+def volume(vol:int) -> None:
+    '''Format: volume [volume:int 0~100]
+    Set the Output Volume of the console to control its output (same as OpenNARS)'''
+    if 0 <= vol <= 100:
+        current_NARS_interface.silence_value = 1 - vol * 0.01 # same as `(100-vol)/100`
+        current_NARS_interface.print_output(
+            type=PrintType.INFO, content=f'''Volume is set to "*volume={vol}".''')
+    else:
+        current_NARS_interface.print_output(
+            type=PrintType.INFO, content=f'''Volume {vol} is out of range 0~100!''')
+
+
 @cmd_register(('toggle-color', 'color'))
 def toggle_color() -> None:
     '''Toggle the color display of cmds (for terminals that do not support custom foreground/background colors)'''

pynars/Interface.py

@@ -204,6 +204,10 @@ def change_random_seed(seed: int) -> None:
                          f'Changing random seed={seed}...', comment_title='Setup')
 
     silent_output: bool = False
+    'determines whether the output is hidden or not'
+
+    silence_value: float = 0.5
+    'determines the level (min threshold of total budget) of output (NARSOutput) generate, only affects the narsese output'
 
     # reasoner
     _NARS: Reasoner = None  # ! internal
@@ -231,6 +235,7 @@ def __init__(self, seed=-1, NARS: reasoner = None, silent: bool = False) -> None
 
         # config
         self.silent_output: bool = silent
+        self.silence_value = 0
 
         # reasoner
         self.print_output(
@@ -375,18 +380,33 @@ def _handle_lines(self, lines: str) -> List[NARSOutput]:
         for task_line in task_list:
             tasks_derived, judgement_revised, goal_revised, answers_question, answers_quest,\
                 (task_operation_return, task_executed) = task_line
+            # * only the 'OUT' will be affected by silence level
             for derived_task in tasks_derived:
-                outs.append(
-                    NARSOutput(
-                        PrintType.OUT, derived_task.sentence.repr(), *derived_task.budget)
-                )
+                '''
+                Ref. OpenNARS 3.1.2 Memory.java line 291~294
+                    ```
+                    float s = task.getBudget().totalBudget();
+                    float minSilent = reasoner.getSilenceValue().get() / 100.0f;
+                    if (s > minSilent) {  // only report significant derived Tasks
+                        //generalInfoReport("4");
+                        report(task.getSentence(), false, false);
+                    }
+                    ```
+                '''
+                if derived_task.budget.total > self.silence_value:
+                    outs.append(
+                        NARSOutput(
+                            PrintType.OUT, derived_task.sentence.repr(), *derived_task.budget)
+                    )
 
             if judgement_revised is not None:
-                outs.append(NARSOutput(PrintType.OUT, judgement_revised.sentence.repr(
-                ), *judgement_revised.budget))
+                if judgement_revised.budget.total > self.silence_value:
+                    outs.append(NARSOutput(
+                        PrintType.OUT, judgement_revised.sentence.repr(), *judgement_revised.budget))
             if goal_revised is not None:
-                outs.append(NARSOutput(
-                    PrintType.OUT, goal_revised.sentence.repr(), *goal_revised.budget))
+                if judgement_revised.budget.total > self.silence_value:
+                    outs.append(NARSOutput(
+                        PrintType.OUT, goal_revised.sentence.repr(), *goal_revised.budget))
             if answers_question is not None:
                 for answer in answers_question:
                     outs.append(

pynars/Narsese/_py/Budget.py

@@ -51,4 +51,18 @@ def distribute(self, n: int):
             return new BudgetValue(priority, b.getDurability(), b.getQuality(), narParameters);
             ```
         '''
-        return Budget(self.priority/sqrt((n if n > 0 else 1)), self.durability, self.quality)
+        return Budget(self.priority/sqrt((n if n > 0 else 1)), self.durability, self.quality)
+
+    @property
+    def total(self) -> float:
+        '''
+        To summarize a BudgetValue into a single number in [0, 1]
+        It's used for introduce the 'volume' by comparing with the number of silence level
+        Ref. OpenNARS 3.1.2 BudgetValue.java line 194~200:
+            ```
+            public float totalBudget() {
+                return UtilityFunctions.aveGeo(priority.getValue(), durability.getValue(), quality.getValue());
+            }
+            ```
+        '''
+        return (self.priority * self.durability * self.quality)**(1/3)