vulcan-core 1.2.1__py3-none-any.whl

vulcan_core/engine.py

@@ -0,0 +1,287 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2025 Latchfield Technologies http://latchfield.com
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from functools import cached_property, partial
+from types import MappingProxyType
+from typing import TYPE_CHECKING
+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."""
+
+
+class RecursionLimitError(RuntimeError):
+    """Raised when the recursion limit is reached during rule evaluation."""
+
+
+@dataclass(frozen=True)
+class Rule:
+    """
+    Represents a rule with a condition and corresponding actions.
+
+    Attributes:
+        - id (UUID): A unique identifier for the rule, automatically generated.
+        - name (Optional[str]): The name of the rule.
+        - when (Expression): The condition that triggers the rule.
+        - then (Action): The action to be executed when the condition is met.
+        - inverse (Optional[Action]): An optional action to be executed when the condition is not met.
+    """
+
+    id: UUID = field(default_factory=uuid4, init=False)
+    name: str | None
+    when: Expression
+    then: Action
+    inverse: Action | None
+
+
+# TODO: Look into support for langchain operators and lang graph integration
+
+
+@dataclass(kw_only=True)
+class RuleEngine:
+    """
+    RuleEngine is a class that manages the evaluation of rules based on a set of facts. It allows for the addition of rules,
+    updating of facts, and cascading evaluation of rules.
+
+    Attributes:
+        enabled (bool): Indicates whether the rule engine is enabled.
+        recusion_limit (int): The maximum number of recursive evaluations allowed.
+        facts (dict[type[Fact], Fact]): A dictionary to store facts with their types as keys.
+        rules (dict[str, list[Rule]]): A dictionary to store rules associated with fact strings.
+
+    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, 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) -> Mapping[str, Fact]:
+        return MappingProxyType(self._facts)
+
+    @cached_property
+    def rules(self) -> Mapping[str, list[Rule]]:
+        return MappingProxyType(self._rules)
+
+    def __getitem__[T: Fact](self, key: type[T]) -> T:
+        """
+        Retrieves a fact from the working memory.
+
+        Args:
+            key (type[Fact]): The type of the fact to retrieve.
+
+        Returns:
+            T: The fact instance of the specified type.
+        """
+        return self._facts[key.__name__]  # type: ignore
+
+    def fact(self, fact: Fact | partial[Fact]):
+        """
+        Updates the working memory with a new fact or merges a partial fact.
+
+        Args:
+            fact (Union[Fact, partial[Fact]]): The fact instance or partial fact to update the working memory with.
+
+        Raises:
+            InternalStateError: If a partial fact cannot be instantiated due to missing required fields
+        """
+        # TODO: Figure out how to track only fact attributes that have changed, and fire on affected rules
+
+        if isinstance(fact, partial):
+            fact_name = fact.func.__name__
+            fact_class = fact.func
+            if not issubclass(fact_class, Fact):  # type: ignore
+                raise NotAFactError(fact_class)
+
+            if fact_name in self._facts:
+                self._facts[fact_name] |= fact
+            else:
+                try:
+                    self._facts[fact_name] = fact()
+                except TypeError as err:
+                    msg = f"Fact '{fact_name}' is missing and lacks sufficient defaults to create from partial: {fact}"
+                    raise InternalStateError(msg) from err
+        else:
+            fact_class = type(fact)
+            if not issubclass(fact_class, Fact):
+                raise NotAFactError(fact_class)
+
+            self._facts[type(fact).__name__] = fact
+
+    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.
+
+        Args:
+            name (Optional[str]): The name of the rule. Defaults to None.
+            when (Expression): The condition that triggers the rule.
+            then (Action): The action to be executed when the condition is met.
+            inverse (Optional[Action]): The action to be executed when the condition is not met. Defaults to None.
+
+        Returns:
+            None
+        """
+        rule = Rule(name, when, then, inverse)
+
+        # TODO: Add automatic inverse option?
+
+        # Update the facts to rule mapping
+        for fact_str in when.facts:
+            if fact_str in self._rules:
+                self._rules[fact_str].append(rule)
+            else:
+                self._rules[fact_str] = [rule]
+
+    def _update_facts(self, fact: tuple[Fact | partial[Fact], ...] | partial[Fact] | Fact) -> list[str]:
+        """
+        Updates the fact in the facts dictionary. If the provided fact is an instance of Fact, it updates the dictionary
+        with the type of the fact as the key. If the provided fact is a partial function, it updates the dictionary with
+        the function of the partial as the key.
+
+        Args:
+            fact (tuple[Fact | partial[Fact], ...] | partial[Fact] | Fact): The fact(s) to be updated, either as an instance of Fact, a partial function, or a tuple of either.
+
+        Returns:
+            Iterator[str]: An iterator over the fact strings of the updated facts.
+        """
+        facts = fact if isinstance(fact, tuple) else (fact,)
+        updated = []
+
+        for f in facts:
+            self.fact(f)
+
+            # Track which attributes were updated
+            if isinstance(f, partial):
+                fact_name = f.func.__name__
+                attrs = f.keywords
+            else:
+                fact_name = f.__class__.__name__
+                attrs = vars(f)
+
+            updated.extend([f"{fact_name}.{attr}" for attr in attrs])
+
+        return updated
+
+    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 [facts[key.split(".")[0]] for key in keys]
+
+    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
+        """
+        evaluated_rules: set[UUID] = set()
+        consequence: set[str] = set()
+
+        # TODO: Create an internal consistency check to determine if all referenced Facts are present?
+
+        # TODO: detect cycles in graph before executing
+        # Move to a separate lifecycle step?
+        # Provide option for handling
+
+        # TODO: Check whether fact attributes have actually changed, and only fire rules that are affected
+        if fact:
+            scope = self._update_facts(fact)
+        else:
+            # By default, evaluate all facts
+            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 the rule if it was already evaluated in this iteration (due to matching on another Fact)
+                        if rule.id in evaluated_rules:
+                            continue
+                        evaluated_rules.add(rule.id)
+
+                        # 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
+                        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:
+                            action_result = action(*self._resolve_facts(action, facts_snapshot))
+                            facts = self._update_facts(action_result)
+                            consequence.update(facts)
+
+                        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()
+                evaluated_rules.clear()
+            else:
+                break
+
+    def yaml_report(self) -> str:
+        return self._audit.generate_yaml_report()

vulcan_core/models.py

@@ -0,0 +1,271 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2025 Latchfield Technologies http://latchfield.com
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Callable, Iterator, Mapping
+from copy import copy
+from dataclasses import dataclass
+from enum import StrEnum, auto
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Protocol,
+    Self,
+    dataclass_transform,
+    runtime_checkable,
+)
+
+from langchain.schema import Document
+
+from vulcan_core.util import is_private
+
+if TYPE_CHECKING:  # pragma: no cover - not used at runtime
+    from functools import partial
+
+    from langchain_core.vectorstores import VectorStoreRetriever
+
+type ActionReturn = tuple[partial[Fact] | Fact, ...] | partial[Fact] | Fact
+type ActionCallable = Callable[..., ActionReturn]
+type ConditionCallable = Callable[..., bool | None]
+
+
+# TODO: Consolidate with AttrDict, and/or figure out how to extende from Mapping
+class ImmutableAttrAsDict:
+    """
+    ImmutableAttrAsDict is an abstract base class that provides dictionary-like access to its attributes.
+    """
+
+    def __getitem__(self, key: str) -> Any:
+        try:
+            return getattr(self, self.validate(key))
+        except KeyError:
+            if hasattr(self, "__missing__"):
+                return self.__missing__(key)  # type: ignore
+            else:
+                raise
+
+    def __contains__(self, key: str) -> bool:
+        return hasattr(self, self.validate(key))
+
+    def __iter__(self) -> Iterator[str]:
+        return (key for key in self.__annotations__ if not is_private(key))
+
+    def __len__(self) -> int:
+        return sum(1 for _ in self)
+
+    def validate(self, key: str) -> str:
+        if is_private(key):
+            msg = f"Access denied to private attribute: {key}"
+            raise KeyError(msg)
+
+        if key not in self.__annotations__:
+            raise KeyError(key)
+
+        return key
+
+    def __init__(self):
+        if type(self) is ImmutableAttrAsDict:
+            msg = f"{ImmutableAttrAsDict.__name__} is an abstract class that can not be directly instantiated."
+            raise TypeError(msg)
+
+    def __reversed__(self) -> Iterator[str]:
+        return reversed(list(self))
+
+    def __or__(self, other: dict) -> dict:
+        return dict(self) | other
+
+    def keys(self) -> list[str]:
+        return list(self)
+
+    def values(self) -> list[Any]:
+        return [getattr(self, key) for key in self]
+
+    def items(self) -> list[tuple[str, Any]]:
+        return [(key, getattr(self, key)) for key in self]
+
+    def get(self, key: str, default: Any = None):
+        return getattr(self, self.validate(key), default)
+
+
+@dataclass_transform(kw_only_default=True, frozen_default=True)
+class FactMetaclass(type):
+    """
+    FactMetaclass is a metaclass that modifies the creation of new classes to automatically
+    apply the `dataclass` decorator with `kw_only=True` and `frozen=True` options.
+    """
+
+    def __new__(cls, name: str, bases: tuple[type], class_dict: dict[str, Any], **kwargs: Any):
+        self = super().__new__(cls, name, bases, class_dict, **kwargs)
+        return dataclass(kw_only=True, frozen=True)(self)
+
+    def _is_dataclass_instance(cls) -> bool:
+        """Determine if this is a dataclass instance by looking for __dataclass_fields__"""
+        return "__dataclass_fields__" not in super().__getattribute__("__dict__")
+
+    # TODO: Implement a context manager to allow access to the default class values
+    # BUG: This causes pylance to not report missing attributes, we need a different way to handle f strings... maybe
+    # the __format__ method?
+    def __getattribute__(cls, name):
+        """
+        Returns a {templated} representation of the Fact's public attributes for deferred use in fstrings. This is
+        useful in rule clauses so that IDE autocomplete can be used in fstrings while deferring evaluation of
+        the content."""
+        if name.startswith("_") or cls._is_dataclass_instance():
+            return super().__getattribute__(name)
+        else:
+            return f"{{{cls.__name__}.{name}}}"
+
+
+class Fact(ImmutableAttrAsDict, metaclass=FactMetaclass):
+    """
+    An abstract class that must be used to define rule engine fact schemas and instantiate data into working memory. Facts
+    may be combined with partial facts of the same type using the `|` operator. This is useful for Actions that only
+    need to update a portion of working memory.
+
+    Example: `new_fact = Inventory(apples=1) | partial(Inventory, oranges=2)`
+    """
+
+    def __or__(self, other: partial[Self] | Self) -> Self:
+        """
+        If the right hand operand is a Fact, it is returned as-is. However, if it is a partial Fact, a copy of the
+        lefthand operand is created with the partial Fact's keywords applied.
+        """
+        if isinstance(other, Fact):
+            if type(self) is not type(other):
+                msg = f"Union operator disallowed for types {type(self).__name__} and {type(other).__name__}"
+                raise TypeError(msg)
+
+            return other  # type: ignore
+        else:
+            if type(self) is not other.func:
+                msg = f"Union operator disallowed for types {type(self).__name__} and {other.func}"
+                raise TypeError(msg)
+
+            new_fact = copy(self)
+            for kw, value in other.keywords.items():
+                object.__setattr__(new_fact, kw, value)
+            return new_fact  # type: ignore
+
+
+@dataclass(frozen=True)
+class DeclaresFacts(ABC):
+    facts: tuple[str, ...]
+    # TODO differentiate bettwen facts consumed vs produced for better tracking/diagnostics
+    # Will probably be needed to detecte cycles in the graph
+
+
+@dataclass(frozen=True)
+class FactHandler[T: Callable, R: Any](ABC):
+    func: T
+
+    @abstractmethod
+    def _evaluate(self, *args: Fact) -> R: ...
+
+
+@runtime_checkable
+class HasSource(Protocol):
+    __source__: str
+
+
+class ChunkingStrategy(StrEnum):
+    SENTENCE = auto()
+    PARAGRAPH = auto()
+    PAGE = auto()
+
+
+@dataclass(kw_only=True, slots=True)
+class Similarity(Mapping[str, list[tuple[str, float]]]):
+    # TODO: Figure out how to cache vectors / and results?
+
+    @abstractmethod
+    def __getitem__(self, key: str) -> list[str]:
+        """Vectorizes key and performs similarity search returning a list of matching."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def __contains__(self, key: str) -> bool:
+        """Vectorizes key and performs similarity search returning a boolean if there is at least one match."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def __iadd__(self, value: str) -> Self:
+        raise NotImplementedError
+
+    @abstractmethod
+    def __iter__(self) -> str:
+        raise NotImplementedError
+
+    @abstractmethod
+    def __len__(self) -> int:
+        raise NotImplementedError
+
+
+class ProxyInitializationError(Exception):
+    """Raised when a Proxy class is used without the proxy being initialized."""
+
+
+@dataclass(kw_only=True, slots=True)
+class ProxyLazyLookup(Similarity):
+    _proxy: Similarity | None = None
+
+    @property
+    def proxy(self) -> Similarity:
+        if self._proxy:
+            return self
+        else:
+            msg = "The `proxy` attribute must be set before the class instance can be used."
+            raise ProxyInitializationError(msg)
+
+    @proxy.setter
+    def proxy(self, value: Similarity) -> None:
+        if not self._proxy:
+            self._proxy = value
+        else:
+            msg = "The `proxy` attribute can only be initialized once."
+            raise ProxyInitializationError(msg)
+
+    def __getitem__(self, key: str) -> list[str]:
+        return self.proxy[key]
+
+    def __contains__(self, key: str) -> bool:
+        raise NotImplementedError
+
+    def __iadd__(self, value: str) -> Self:
+        self.proxy += value
+        return self
+
+    def __iter__(self) -> str:
+        raise NotImplementedError
+
+    def __len__(self) -> int:
+        raise NotImplementedError
+
+
+@dataclass(kw_only=True, slots=True)
+class RetrieverAdapter(Similarity):
+    """A lazy lookup that uses the Chroma vector store to perform similarity searches using OpenAI embeddings."""
+
+    store: VectorStoreRetriever
+
+    def __getitem__(self, key: str) -> list[str]:
+        """Vectorizes key and performs similarity search returning a list of matching content."""
+        return [doc.page_content for doc in self.store.invoke(key)]
+
+    def __contains__(self, key: str) -> bool:
+        """Vectorizes key and performs similarity search returning a boolean if there is at least one match."""
+        raise NotImplementedError
+
+    def __iadd__(self, value: str) -> Self:
+        self.store.add_documents([Document(value)])
+        return self
+
+    def __iter__(self) -> str:
+        raise NotImplementedError
+
+    def __len__(self) -> int:
+        raise NotImplementedError
+
+    def __str__(self) -> str:
+        return f"RetrieverAdapter(search_type={self.store.search_type})"