feat: add value sharing (#44)

* feat: add value sharing

Signed-off-by: develop-cs <[email protected]>

* docs: add how to get input and output data in functions

Signed-off-by: develop-cs <[email protected]>

* fix: enable other kwargs param name

Signed-off-by: develop-cs <[email protected]>

---------

Signed-off-by: develop-cs <[email protected]>

Author: develop-cs

.github/dependabot.yml

@@ -0,0 +1,14 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    commit-message:
+      prefix: "chore(gh-actions): "
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    commit-message:
+      prefix: "chore(dependencies): "

.pre-commit-config.yaml

@@ -26,29 +26,29 @@ repos:
       - id: check-added-large-files
         args: [--maxkb=500]
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.8.2
+    rev: v0.9.9
     hooks:
       - id: ruff
         args: [--fix]
       - id: ruff-format
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.13.0
+    rev: v1.15.0
     hooks:
       - id: mypy
         args: [--config-file=pyproject.toml]
         files: src
         additional_dependencies: [pydantic~=2.0]
   - repo: https://github.com/gitleaks/gitleaks
-    rev: v8.21.2
+    rev: v8.24.0
     hooks:
       - id: gitleaks
   - repo: https://github.com/pypa/pip-audit
-    rev: v2.7.3
+    rev: v2.8.0
     hooks:
       - id: pip-audit
         args: [--skip-editable]
   - repo: https://github.com/compilerla/conventional-pre-commit
-    rev: v3.6.0
+    rev: v4.0.0
     hooks:
       - id: conventional-pre-commit
         stages: [commit-msg]

CHANGELOG.md

@@ -4,6 +4,13 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.10.0] - March, 2025
+
+### Features
+
+* Ability to share values between validation and action functions (#7).
+* The `kwargs` parameter of action functions is now optional (only mandatory if you need to access `input_data`).
+
 ## [0.9.0] - December, 2024
 
 ### Features

README.md

@@ -78,7 +78,7 @@ actions_source_modules:
 from typing import Any
 
 
-def set_admission(value: bool, **kwargs: Any) -> dict[str, bool]:
+def set_admission(value: bool) -> dict[str, bool]:
     """Return a dictionary containing the admission result."""
     return {"is_admitted": value}
 ```

docs/mkdocs.yaml

@@ -88,6 +88,7 @@ nav:
     - Parameters: parameters.md
     - Rule activation mode: rule_activation_mode.md
     - Rule sets: rule_sets.md
+    - Value sharing: value_sharing.md
     - Use your business objects: business_objects.md
 
 extra_css:

docs/pages/a_simple_example.md

@@ -127,17 +127,17 @@ And could be for example (intentionally simple) in `actions.py`:
 from typing import Any
 
 
-def set_admission(value: bool, **kwargs: Any) -> dict[str, bool]:
+def set_admission(value: bool) -> dict[str, bool]:
     """Return a dictionary containing the admission result."""
     return {"is_admitted": value}
 
 
-def set_course(course_id: str, **kwargs: Any) -> dict[str, str]:
+def set_course(course_id: str) -> dict[str, str]:
     """Return the course id as a dictionary."""
     return {"course_id": course_id}
 
 
-def send_email(mail_to: str, mail_content: str, meal: str, **kwargs: Any) -> str | None:
+def send_email(mail_to: str, mail_content: str, meal: str) -> str | None:
     """Send an email."""
     result: str | None = None
 
@@ -148,10 +148,6 @@ def send_email(mail_to: str, mail_content: str, meal: str, **kwargs: Any) -> str
     return result
 ```
 
-!!! warning "\*\*kwargs"
-
-    **\*\*kwargs** is mandatory in *action functions*.
-
 ### Engine
 
 The *rules engine* is responsible for evaluating the [configured rules](#rules) against some *data* (usually named *"input data"*). 

docs/pages/how_to.md

@@ -227,15 +227,21 @@ def has_authorized_super_power(power):
 **actions.py**:
 
 ```python
-def set_admission(value, **kwargs):  # (1)
+def set_admission(value):
     return {"is_admitted": value}
 ```
 
-1. `**kwargs` is mandatory here.
-
 !!! warning
 
-    Function name and parameters must be the same as the one configured in the YAML file.
+    **Function name** and **parameters** must be the same as the one configured in the YAML file.
+
+!!! tip
+
+    If you need to retrieve some `input_data` or `output` of a previous action in your function, just:
+
+    1. Add a ****kwargs** parameter.
+    1. Access *input_data* with `kwargs["input_data"]["<some-key>"]` where `<some-key>` is a key in the *input data* dictionary (or dict like object).
+    1. Access data from previous rules group with `kwargs["input_data"]["output"]["<a-rule-group-id>"]`.
 
 ### Usage
 
@@ -395,7 +401,7 @@ Both are made of a *callable object* and some *parameters*:
     ```python    
     from arta import RulesEngine
 
-    set_admission = lambda value, **kwargs: {"is_admitted": value}
+    set_admission = lambda value: {"is_admitted": value}
 
     rules = {
         "check_admission": {
@@ -441,7 +447,7 @@ Both are made of a *callable object* and some *parameters*:
 
     from arta import RulesEngine
 
-    set_admission: Callable = lambda value, **kwargs: {"is_admitted": value}
+    set_admission: Callable = lambda value: {"is_admitted": value}
 
     rules: dict[str, Any] = {
         "check_admission": {

docs/pages/value_sharing.md

@@ -0,0 +1,51 @@
+!!! note
+
+    Only available with `arta>=0.10.0`.
+
+
+It is possible to share some informations between **condition** and **action** implementations.
+
+It can be usefull when an **action** needs some data that was computed in a **condition** (e.g., sanity check use cases).
+
+In the following example, a **condition** is computing the *median* of some *input values* and checking it. Then, the **action** retrieves this *median* value and uses it.
+
+
+**Two things have to be done for that:**
+
+1. Add the `**kwargs` parameter in your functions' definition (**validation** and **action** functions) if not already there.
+1. Set some new subkeys in the `input_data` key.
+
+
+**Set the value (in a condition for example):**
+
+```python hl_lines="4 9"
+def is_median_above(
+    values: list[float], 
+    limit: float, 
+    **kwargs: Any,  # (1)
+    ) -> bool:
+    """Check if the median of some values is above limit."""
+    median = statistics.median(values)
+    # Store the value for later use by an action function
+    kwargs["input_data"]["median"] = median  # (2)
+    kwargs["input_data"]["median_limit"] = limit
+    return median > limit
+```
+
+1. Add the ****kwargs** parameter.
+2. Set your value in the `input_data`.
+
+
+**Get the value (in an action for example):**
+
+```python hl_lines="1 4"
+def alert_on_median(**kwargs: Any) -> str:  # (1)
+    """Alert: "Median is too high: 13, limit is: 10."""
+    return (
+        f"Median is too high: {kwargs['input_data']['median']}, "  # (2)
+        f"limit is: {kwargs['input_data']['median_limit']}."
+    )
+```
+
+1. Add the ****kwargs** parameter.
+2. Get the value.

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "arta"
-version = "0.9.0"
+version = "0.10.0"
 requires-python = ">3.8.0"
 description = "A Python Rules Engine - Make rule handling simple"
 readme = "README.md"

src/arta/condition.py

@@ -5,6 +5,7 @@
 
 from __future__ import annotations
 
+import inspect
 import re
 from abc import ABC, abstractmethod
 from typing import Any, Callable
@@ -140,6 +141,11 @@ def verify(self, input_data: dict[str, Any], parsing_error_strategy: ParsingErro
                 parameter=value, input_data=input_data, parsing_error_strategy=parsing_error_strategy
             )
 
+        # Pass input_data for value sharing if validation function can accept it
+        arg_spec: inspect.FullArgSpec = inspect.getfullargspec(self._validation_function)
+        if arg_spec.varkw is not None:
+            parameters["input_data"] = input_data
+
         # Run validation_function
         return self._validation_function(**parameters)
 

src/arta/rule.py

@@ -5,6 +5,7 @@
 
 from __future__ import annotations
 
+import inspect
 import re
 from typing import Any, Callable
 
@@ -105,8 +106,13 @@ def apply(
                 # Track the rule id
                 rule_results["activated_rule"] = self._rule_id
 
+                # Pass input_data for value sharing if action function can accept it
+                arg_spec: inspect.FullArgSpec = inspect.getfullargspec(self._action)
+                if arg_spec.varkw is not None:
+                    parameters["input_data"] = input_data
+
                 # Run action
-                rule_results["action_result"] = self._action(**parameters, input_data=input_data)
+                rule_results["action_result"] = self._action(**parameters)
 
                 return rule_results["action_result"], rule_results
             except Exception as error:

src/arta/utils.py

@@ -11,9 +11,9 @@
 class ParsingErrorStrategy(str, Enum):
     """Define authorized error handling strategies when a key is missing in the input data."""
 
-    RAISE: str = "raise"
-    IGNORE: str = "ignore"
-    DEFAULT_VALUE: str = "default_value"
+    RAISE = "raise"
+    IGNORE = "ignore"
+    DEFAULT_VALUE = "default_value"
 
 
 class RuleActivationMode(str, Enum):
@@ -22,8 +22,8 @@ class RuleActivationMode(str, Enum):
     ONE_BY_GROUP is the default mode.
     """
 
-    ONE_BY_GROUP: str = "one_by_group"
-    MANY_BY_GROUP: str = "many_by_group"
+    ONE_BY_GROUP = "one_by_group"
+    MANY_BY_GROUP = "many_by_group"
 
 
 def get_value_in_nested_dict_from_path(path: str, nested_dict: dict[str, Any]) -> Any:

tests/examples/code/actions.py

@@ -9,7 +9,7 @@
 from typing import Any
 
 
-def set_admission(value: bool, **kwargs: Any) -> dict[str, bool]:
+def set_admission(value: bool) -> dict[str, bool]:
     """Return a dictionary containing the admission result."""
     return {"admission": value}
 
@@ -19,7 +19,7 @@ def set_student_course(course_id: str, **kwargs: Any) -> dict[str, str]:
     return {"course_id": course_id}
 
 
-def send_email(mail_to: str, mail_content: str, meal: str, **kwargs: Any) -> bool:
+def send_email(mail_to: str, mail_content: str, meal: str) -> bool:
     """Send an email and return True if OK."""
     is_ok = False
 
@@ -30,7 +30,7 @@ def send_email(mail_to: str, mail_content: str, meal: str, **kwargs: Any) -> boo
     return is_ok
 
 
-def concatenate_list(list_str: list[Any], **kwargs: Any) -> str:
+def concatenate_list(list_str: list[Any], **extra: Any) -> str:
     """Demo function: return the concatenation of a list of string using input_data (two levels max)."""
     list_str = [str(element) for element in list_str]
     return "".join(list_str)
@@ -46,6 +46,11 @@ def compute_sum(value1: float, value2: float, **kwargs: Any) -> float:
     return value1 + value2
 
 
-def concatenate(value1: str, value2: str, **kwargs: Any) -> str:
+def concatenate(value1: str, value2: str) -> str:
     """Demo function: return the concatenation of two strings."""
     return value1 + value2
+
+
+def alert_on_median(**kwargs: Any) -> str:
+    """Alert: "Median is too high: 13, limit is: 10."""
+    return f"Median is too high: {kwargs['input_data']['median']}, limit is: {kwargs['input_data']['median_limit']}."

tests/examples/code/conditions.py

@@ -5,6 +5,8 @@
 """
 
 from __future__ import annotations
+import statistics
+from typing import Any
 
 
 def has_authorized_super_power(authorized_powers: list[str], candidate_powers: list[str]) -> bool:
@@ -23,6 +25,15 @@ def is_speaking_language(value: str, spoken_language: str) -> bool:
     return value == spoken_language
 
 
-def has_favorite_meal(favorite_meal: str) -> bool:
+def has_favorite_meal(favorite_meal: str, **extra: Any) -> bool:
     """Check if candidate has a favorite meal."""
     return favorite_meal is not None
+
+
+def is_median_above(values: list[int | float], limit: float, **kwargs: Any) -> bool:
+    """Check if the median of some values is above limit."""
+    median = statistics.median(values)
+    # Store the value for later use by an action function
+    kwargs["input_data"]["median"] = median
+    kwargs["input_data"]["median_limit"] = limit
+    return median > limit

tests/examples/good_conf/conditions.yaml

@@ -6,21 +6,21 @@ conditions:
     validation_function: has_authorized_super_power
     condition_parameters:
       authorized_powers:
-      - "strength"
-      - "fly"
-      - "immortality"
+      - strength
+      - fly
+      - immortality
       candidate_powers: input.powers
   IS_SPEAKING_FRENCH:
     description: "Does it speak french?"
     validation_function: is_speaking_language
     condition_parameters:
-      value: "french"
+      value: french
       spoken_language: input.language
   IS_SPEAKING_ENGLISH:
     description: "Does it speak english?"
     validation_function: is_speaking_language
     condition_parameters:
-      value: "english"
+      value: english
       spoken_language: input.language
   IS_AGE_UNKNOWN:
     description: "Do we know his age?"

tests/examples/value_sharing/rules.yaml

@@ -0,0 +1,20 @@
+---
+rules:
+  default_rule_set:
+    median_check:
+      MEDIAN_KO:
+        condition: IS_MEDIAN_ABOVE_10
+        action: alert_on_median
+
+conditions:
+  IS_MEDIAN_ABOVE_10:
+    description: "Is the computed median above 10?"
+    validation_function: is_median_above
+    condition_parameters:
+      values: input.values
+      limit: 10
+
+conditions_source_modules:
+  - "tests.examples.code.conditions"
+actions_source_modules:
+  - "tests.examples.code.actions"