vulcan-core 1.1.4__py3-none-any.whl → 1.2.0__py3-none-any.whl

vulcan_core/engine.py

@@ -3,6 +3,7 @@
 
 from __future__ import annotations
 
+import logging
 from dataclasses import dataclass, field
 from functools import cached_property, partial
 from types import MappingProxyType
@@ -11,11 +12,16 @@ from uuid import UUID, uuid4
 
 from vulcan_core.ast_utils import NotAFactError
 from vulcan_core.models import DeclaresFacts, Fact
+from vulcan_core.reporting import Auditor
 
 if TYPE_CHECKING:  # pragma: no cover - not used at runtime
+    from collections.abc import Mapping
+
     from vulcan_core.actions import Action
     from vulcan_core.conditions import Expression
 
+logger = logging.getLogger(__name__)
+
 
 class InternalStateError(RuntimeError):
     """Raised when the internal state of the RuleEngine is invalid."""
@@ -63,20 +69,22 @@ class RuleEngine:
     Methods:
         rule(self, *, name: str | None = None, when: LogicEvaluator, then: BaseAction, inverse: BaseAction | None = None): Adds a rule to the rule engine.
         update_facts(self, fact: tuple[Fact | partial[Fact], ...] | partial[Fact] | Fact) -> Iterator[str]: Updates the facts in the working memory.
-        evaluate(self): Evaluates the rules based on the current facts in working memory.
+        evaluate(self, trace: bool = False): Evaluates the rules based on the current facts in working memory.
+        yaml_report(self): Returns the YAML report of the last evaluation (if tracing was enabled).
     """
 
     enabled: bool = False
     recusion_limit: int = 10
     _facts: dict[str, Fact] = field(default_factory=dict, init=False)
     _rules: dict[str, list[Rule]] = field(default_factory=dict, init=False)
+    _audit: Auditor = field(default_factory=Auditor, init=False)
 
     @cached_property
-    def facts(self) -> MappingProxyType[str, Fact]:
+    def facts(self) -> Mapping[str, Fact]:
         return MappingProxyType(self._facts)
 
     @cached_property
-    def rules(self) -> MappingProxyType[str, list[Rule]]:
+    def rules(self) -> Mapping[str, list[Rule]]:
         return MappingProxyType(self._rules)
 
     def __getitem__[T: Fact](self, key: type[T]) -> T:
@@ -124,7 +132,9 @@ class RuleEngine:
 
             self._facts[type(fact).__name__] = fact
 
-    def rule[T: Fact](self, *, name: str | None = None, when: Expression, then: Action, inverse: Action | None = None) -> None:
+    def rule[T: Fact](
+        self, *, name: str | None = None, when: Expression, then: Action, inverse: Action | None = None
+    ) -> None:
         """
         Convenience method for adding a rule to the rule engine.
 
@@ -178,18 +188,22 @@ class RuleEngine:
 
         return updated
 
-    def _resolve_facts(self, declared: DeclaresFacts) -> list[Fact]:
+    def _resolve_facts(self, declared: DeclaresFacts, facts: dict[str, Fact]) -> list[Fact]:
         # Deduplicate the fact strings and retrieve unique fact instances
         keys = {key.split(".")[0]: key for key in declared.facts}.values()
-        return [self._facts[key.split(".")[0]] for key in keys]
+        return [facts[key.split(".")[0]] for key in keys]
 
-    def evaluate(self, fact: Fact | partial[Fact] | None = None):
+    def evaluate(self, fact: Fact | partial[Fact] | None = None, *, audit: bool = False):
         """
         Cascading evaluation of rules based on the facts in working memory.
 
         If provided a fact, will update and evaluate immediately. Otherwise all rules will be evaluated.
+
+        Args:
+            fact: Optional fact to update and evaluate immediately
+            audit: Enables tracing for explanbility report generation
         """
-        fired_rules: set[UUID] = set()
+        evaluated_rules: set[UUID] = set()
         consequence: set[str] = set()
 
         # TODO: Create an internal consistency check to determine if all referenced Facts are present?
@@ -206,37 +220,68 @@ class RuleEngine:
             fact_list = self._facts.values()
             scope = {f"{fact.__class__.__name__}.{attr}" for fact in fact_list for attr in vars(fact)}
 
+        if audit:
+            self._audit.evaluation_reset()
+
         # Iterate over the rules until the recusion limit is reached or no new rules are fired
         for iteration in range(self.recusion_limit + 1):
             if iteration == self.recusion_limit:
                 msg = f"Recursion limit of {self.recusion_limit} reached"
                 raise RecursionLimitError(msg)
 
+            # Ensure that rules do not interfere with one another in the same iteration
+            facts_snapshot = self._facts.copy()
+
+            if audit:
+                self._audit.iteration_start()
+
+            # Evaluate matching rules
             for fact_str, rules in self._rules.items():
                 if fact_str in scope:
                     for rule in rules:
-                        # Skip if we already evaluated the rule this iteration
-                        if rule.id in fired_rules:
+                        # Skip the rule if it was already evaluated in this iteration (due to matching on another Fact)
+                        if rule.id in evaluated_rules:
                             continue
-                        fired_rules.add(rule.id)
+                        evaluated_rules.add(rule.id)
 
-                        # Evaluate the rule's 'when' and determine which action to invoke
+                        # Skip if not all facts required by the rule are present
+                        try:
+                            resolved_facts = self._resolve_facts(rule.when, facts_snapshot)
+                        except KeyError as e:
+                            logger.debug("Rule %s (%s) skipped due to missing fact: %s", rule.name, rule.id, str(e))
+                            continue
+
+                        if audit:
+                            self._audit.rule_start()
+
+                        # Evaluate the rule and prepare the aciton
                         action = None
-                        if rule.when(*self._resolve_facts(rule.when)):
+                        condition_result = rule.when(*resolved_facts)
+                        if condition_result:
                             action = rule.then
                         elif rule.inverse:
                             action = rule.inverse
 
+                        # Evaluate the action and update the consequences
+                        action_result = None
                         if action:
-                            # Update the facts and track consequences to fire subsequent rules
-                            result = action(*self._resolve_facts(action))
-                            facts = self._update_facts(result)
+                            action_result = action(*self._resolve_facts(action, facts_snapshot))
+                            facts = self._update_facts(action_result)
                             consequence.update(facts)
 
-            # If rules updated some facts, prepare for the next iteration
+                        if audit:
+                            self._audit.rule_end(rule, action_result, facts_snapshot, condition_result=condition_result)
+
+            if audit:
+                self._audit.iteration_end()
+
+            # Check for next iteration
             if consequence:
                 scope = consequence
                 consequence = set()
-                fired_rules.clear()
+                evaluated_rules.clear()
             else:
                 break
+
+    def yaml_report(self) -> str:
+        return self._audit.generate_yaml_report()

vulcan_core/models.py

@@ -28,7 +28,7 @@ if TYPE_CHECKING:  # pragma: no cover - not used at runtime
 
 type ActionReturn = tuple[partial[Fact] | Fact, ...] | partial[Fact] | Fact
 type ActionCallable = Callable[..., ActionReturn]
-type ConditionCallable = Callable[..., bool]
+type ConditionCallable = Callable[..., bool | None]
 
 
 # TODO: Consolidate with AttrDict, and/or figure out how to extende from Mapping
@@ -161,7 +161,7 @@ class FactHandler[T: Callable, R: Any](ABC):
     func: T
 
     @abstractmethod
-    def __call__(self, *args: Fact) -> R: ...
+    def _evaluate(self, *args: Fact) -> R: ...
 
 
 @runtime_checkable