lionagi 0.1.1__py3-none-any.whl → 0.2.0__py3-none-any.whl

lionagi/core/rule/base.py

@@ -0,0 +1,238 @@
+"""
+Copyright 2024 HaiyangLi
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+"""
+
+from abc import abstractmethod
+from typing import Any, List, Dict
+from pandas import Series
+from lionagi.libs import SysUtil
+
+from lionagi.core.collections.abc import FieldError, Condition, Actionable, Component
+
+_rule_classes = {}
+
+
+class Rule(Component, Condition, Actionable):
+    """
+    Combines a condition and an action that can be applied based on it.
+
+    Attributes:
+        apply_type (str): The type of data to which the rule applies.
+        fix (bool): Indicates whether the rule includes a fix action.
+        fields (list[str]): List of fields to which the rule applies.
+        validation_kwargs (dict): Keyword arguments for validation.
+        applied_log (list): Log of applied rules.
+        invoked_log (list): Log of invoked rules.
+        _is_init (bool): Indicates whether the rule is initialized.
+    """
+
+    exclude_type: list[str] = []
+    apply_type: list[str] | str = None
+    fix: bool = True
+    fields: list[str] = []
+    validation_kwargs: dict = {}
+    applied_log: list = []
+    invoked_log: list = []
+    _is_init: bool = False
+
+    def __init_subclass__(cls, **kwargs):
+        super().__init_subclass__(**kwargs)
+        if cls.__name__ not in _rule_classes:
+            _rule_classes[cls.__name__] = cls
+
+    def add_log(self, field: str, form: Any, apply: bool = True, **kwargs) -> None:
+        """
+        Adds an entry to the applied or invoked log.
+
+        Args:
+            field (str): The field being validated.
+            form (Any): The form being validated.
+            apply (bool): Indicates whether the log is for an applied rule.
+            **kwargs: Additional configuration parameters.
+        """
+        a = {
+            "type": "rule",
+            "class": self.class_name,
+            "ln_id": self.ln_id,
+            "timestamp": SysUtil.get_timestamp(sep=None)[:-6],
+            "field": field,
+            "form": form.ln_id,
+            "config": kwargs,
+        }
+        if apply:
+            self.applied_log.append(a)
+        else:
+            self.invoked_log.append(a)
+
+    async def applies(
+        self,
+        field: str,
+        value: Any,
+        form: Any,
+        *args,
+        annotation: List[str] = None,
+        use_annotation: bool = True,
+        **kwargs,
+    ) -> bool:
+        """
+        Determines whether the rule applies to a given field and value.
+
+        Args:
+            field (str): The field being validated.
+            value (Any): The value of the field.
+            form (Any): The form being validated.
+            *args: Additional arguments.
+            annotation (list[str], optional): Annotations for the field.
+            use_annotation (bool): Indicates whether to use annotations.
+            **kwargs: Additional keyword arguments.
+
+        Returns:
+            bool: True if the rule applies, otherwise False.
+        """
+        if self.fields:
+            if field in self.fields:
+                self.add_log(field, form, **kwargs)
+                return True
+
+        if use_annotation:
+            annotation = annotation or form._get_field_annotation(field)
+            annotation = [annotation] if isinstance(annotation, str) else annotation
+
+            for i in annotation:
+                if i in self.apply_type and i not in self.exclude_type:
+                    self.add_log(field, form, **kwargs)
+                    return True
+            return False
+
+        a = await self.rule_condition(field, value, *args, **kwargs)
+
+        if a:
+            self.add_log(field, form, **kwargs)
+            return True
+        return False
+
+    async def invoke(self, field: str, value: Any, form: Any) -> Any:
+        """
+        Invokes the rule's validation logic on a field and value.
+
+        Args:
+            field (str): The field being validated.
+            value (Any): The value of the field.
+            form (Any): The form being validated.
+
+        Returns:
+            Any: The validated or fixed value.
+
+        Raises:
+            ValueError: If validation or fixing fails.
+        """
+        try:
+            a = await self.validate(value, **self.validation_kwargs)
+            self.add_log(field, form, apply=False, **self.validation_kwargs)
+            return a
+
+        except Exception as e1:
+            if self.fix:
+                try:
+                    a = await self.perform_fix(value, **self.validation_kwargs)
+                    self.add_log(field, form, apply=False, **self.validation_kwargs)
+                    return a
+                except Exception as e2:
+                    raise FieldError(f"failed to fix field") from e2
+            raise FieldError(f"failed to validate field") from e1
+
+    async def rule_condition(self, field, value, *args, **kwargs) -> bool:
+        """
+        Additional condition, if choosing not to use annotation as a qualifier.
+
+        Args:
+            *args: Additional arguments.
+            **kwargs: Additional keyword arguments.
+
+        Returns:
+            bool: False by default, should be overridden by subclasses.
+        """
+        return False
+
+    async def perform_fix(self, value: Any, *args, **kwargs) -> Any:
+        """
+        Attempts to fix a value if validation fails.
+
+        Args:
+            value (Any): The value to fix.
+            *args: Additional arguments.
+            **kwargs: Additional keyword arguments.
+
+        Returns:
+            Any: The fixed value.
+
+        Raises:
+            ValueError: If the fix fails.
+        """
+        return value
+
+    @abstractmethod
+    async def validate(self, value: Any) -> Any:
+        """
+        Abstract method to validate a value.
+
+        Args:
+            value (Any): The value to validate.
+
+        Returns:
+            Any: The validated value.
+
+        Raises:
+            ValueError: If validation fails.
+        """
+        pass
+
+    def _to_dict(self) -> Dict[str, Any]:
+        """
+        Converts the rule's attributes to a dictionary.
+
+        Returns:
+            dict: A dictionary representation of the rule.
+        """
+        return {
+            "ln_id": self.ln_id[:8] + "...",
+            "rule": self.__class__.__name__,
+            "apply_type": self.apply_type,
+            "fix": self.fix,
+            "fields": self.fields,
+            "validation_kwargs": self.validation_kwargs,
+            "num_applied": len(self.applied_log),
+            "num_invoked": len(self.invoked_log),
+        }
+
+    def __str__(self) -> str:
+        """
+        Returns a string representation of the rule using a pandas Series.
+
+        Returns:
+            str: A string representation of the rule.
+        """
+        series = Series(self._to_dict())
+        return series.__str__()
+
+    def __repr__(self) -> str:
+        """
+        Returns a string representation of the rule using a pandas Series.
+
+        Returns:
+            str: A string representation of the rule.
+        """
+        series = Series(self._to_dict())
+        return series.__repr__()

lionagi/core/rule/boolean.py

@@ -0,0 +1,56 @@
+from typing import Any
+from lionagi.libs.ln_convert import to_str, strip_lower
+from lionagi.core.rule.base import Rule
+
+
+class BooleanRule(Rule):
+    """
+    Rule for validating that a value is a boolean.
+
+    Attributes:
+        apply_type (str): The type of data to which the rule applies.
+    """
+
+    fields: list[str] = ["action_required"]
+
+    def __init__(self, apply_type="bool", **kwargs):
+        super().__init__(apply_type=apply_type, **kwargs)
+
+    async def validate(self, value: Any) -> bool:
+        """
+        Validate that the value is a boolean.
+
+        Args:
+            value (Any): The value to validate.
+
+        Returns:
+            bool: The validated value.
+
+        Raises:
+            ValueError: If the value is not a valid boolean.
+        """
+        if isinstance(value, bool):
+            return value
+        raise ValueError(f"Invalid boolean value.")
+
+    async def perform_fix(self, value: Any) -> bool:
+        """
+        Attempt to fix the value by converting it to a boolean.
+
+        Args:
+            value (Any): The value to fix.
+
+        Returns:
+            bool: The fixed value.
+
+        Raises:
+            ValueError: If the value cannot be converted to a boolean.
+        """
+        value = strip_lower(to_str(value))
+        if value in ["true", "1", "correct", "yes"]:
+            return True
+
+        elif value in ["false", "0", "incorrect", "no", "none", "n/a"]:
+            return False
+
+        raise ValueError(f"Failed to convert {value} into a boolean value")

lionagi/core/rule/choice.py

@@ -0,0 +1,47 @@
+from lionagi.libs.ln_parse import StringMatch
+from lionagi.core.rule.base import Rule
+
+
+class ChoiceRule(Rule):
+    """
+    Rule for validating that a value is within a set of predefined choices.
+
+    Attributes:
+        apply_type (str): The type of data to which the rule applies.
+        keys (list): The list of valid choices.
+    """
+
+    def __init__(self, apply_type="enum", **kwargs):
+        super().__init__(apply_type=apply_type, **kwargs)
+        self.keys = self.validation_kwargs.get("keys", None)
+
+    async def validate(self, value: str, *args, **kwargs) -> str:
+        """
+        Validate that the value is within the set of predefined choices.
+
+        Args:
+            value (str): The value to validate.
+            *args: Additional arguments.
+            **kwargs: Additional keyword arguments.
+
+        Returns:
+            str: The validated value.
+
+        Raises:
+            ValueError: If the value is not in the set of choices.
+        """
+        if not value in self.keys:
+            raise ValueError(f"{value} is not in chocies {self.keys}")
+        return value
+
+    async def perform_fix(self, value):
+        """
+        Suggest a fix for a value that is not within the set of predefined choices.
+
+        Args:
+            value (str): The value to suggest a fix for.
+
+        Returns:
+            str: The most similar value from the set of predefined choices.
+        """
+        return StringMatch.choose_most_similar(value, self.keys)

lionagi/core/rule/mapping.py

@@ -0,0 +1,96 @@
+"""
+Copyright 2024 HaiyangLi
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+"""
+
+from typing import Any
+from collections.abc import Mapping
+from lionagi.libs.ln_convert import to_dict
+from lionagi.libs import StringMatch, ParseUtil
+
+from lionagi.core.rule.choice import ChoiceRule
+
+
+class MappingRule(ChoiceRule):
+    """
+    Rule for validating that a value is a mapping (dictionary) with specific keys.
+
+    Attributes:
+        apply_type (str): The type of data to which the rule applies.
+    """
+
+    def __init__(self, apply_type="dict", **kwargs):
+        super().__init__(apply_type=apply_type, **kwargs)
+
+    async def validate(self, value: Any, *args, **kwargs) -> Any:
+        """
+        Validate that the value is a mapping with specific keys.
+
+        Args:
+            value (Any): The value to validate.
+            *args: Additional arguments.
+            **kwargs: Additional keyword arguments.
+
+        Returns:
+            Any: The validated value.
+
+        Raises:
+            ValueError: If the value is not a valid mapping or has incorrect keys.
+        """
+        if not isinstance(value, Mapping):
+            raise ValueError("Invalid mapping field type.")
+
+        if self.keys:
+            if (keys := set(value.keys())) != set(self.keys):
+                raise ValueError(
+                    f"Invalid mapping keys. Current keys {[i for i in keys]} != {self.keys}"
+                )
+        return value
+
+    async def perform_fix(self, value: Any, *args, **kwargs) -> Any:
+        """
+        Attempt to fix the value by converting it to a dict and validating its keys.
+
+        Args:
+            value (Any): The value to fix.
+            *args: Additional arguments.
+            **kwargs: Additional keyword arguments.
+
+        Returns:
+            Any: The fixed value.
+
+        Raises:
+            ValueError: If the value cannot be fixed.
+        """
+        if not isinstance(value, dict):
+            try:
+                value = to_dict(value)
+            except Exception as e:
+                raise ValueError("Invalid dict field type.") from e
+
+        if self.keys:
+            check_keys = set(value.keys())
+            if check_keys != set(self.keys):
+                try:
+                    return StringMatch.force_validate_dict(value, keys=self.keys)
+                except Exception as e:
+                    raise ValueError("Invalid dict keys.") from e
+
+        else:
+            try:
+                return ParseUtil.fuzzy_parse_json(value)
+            except Exception as e:
+                raise ValueError("Invalid dict keys.") from e
+
+        return value

lionagi/core/rule/number.py

@@ -0,0 +1,71 @@
+from typing import Any
+from lionagi.libs.ln_convert import to_num
+from lionagi.core.rule.base import Rule
+
+
+class NumberRule(Rule):
+    """
+    Rule for validating that a value is a number within specified bounds.
+
+    Attributes:
+        apply_type (str): The type of data to which the rule applies.
+        upper_bound (int | float | None): The upper bound for the value.
+        lower_bound (int | float | None): The lower bound for the value.
+        num_type (Type[int | float]): The type of number (int or float).
+        precision (int | None): The precision for floating point numbers.
+    """
+
+    fields: list[str] = ["confidence_score", "score"]
+
+    def __init__(self, apply_type="int, float", **kwargs):
+        super().__init__(apply_type=apply_type, **kwargs)
+        self.upper_bound = self.validation_kwargs.get("upper_bound")
+        self.lower_bound = self.validation_kwargs.get("lower_bound")
+        self.num_type = self.validation_kwargs.get("num_type", float)
+        self.precision = self.validation_kwargs.get("precision")
+
+    async def validate(self, value: Any) -> Any:
+        """
+        Validate that the value is a number.
+
+        Args:
+            value (Any): The value to validate.
+
+        Returns:
+            Any: The validated value.
+
+        Raises:
+            ValueError: If the value is not a valid number.
+        """
+        if isinstance(value, (int, float)):
+            return value
+        raise ValueError(f"Invalid number field: {value}")
+
+    async def perform_fix(self, value: Any) -> Any:
+        """
+        Attempt to fix the value by converting it to a number.
+
+        Args:
+            value (Any): The value to fix.
+
+        Returns:
+            Any: The fixed value.
+
+        Raises:
+            ValueError: If the value cannot be converted to a number.
+        """
+        if isinstance(value, (int, float)):
+            return value
+
+        value = to_num(
+            value,
+            **{
+                k: v
+                for k, v in self.validation_kwargs.items()
+                if k in ["num_type", "precision", "upper_bound", "lower_bound"]
+            },
+        )
+
+        if isinstance(value, (int, float)):
+            return value
+        raise ValueError(f"Failed to convert {value} into a numeric value")

lionagi/core/rule/rulebook.py

@@ -0,0 +1,109 @@
+from lionagi.libs.ln_func_call import lcall
+from lionagi.core.rule.base import Rule
+
+
+"""
+rule config schema 
+
+{
+    rule_name: {
+        "fields: [],
+        "config": {}, 
+        ...
+    }
+}
+"""
+
+
+class RuleBook:
+
+    def __init__(
+        self,
+        rules: dict[str, Rule] | list[Rule] = None,
+        ruleorder: list[str] = None,
+        rule_config: dict[str, dict] = None,
+    ):
+        self.rules = rules
+        self.ruleorder = ruleorder
+        self.rule_config = rule_config or {k: {} for k in self.ruleorder}
+
+    @property
+    def _all_applied_log(self):
+        """return all applied logs from all rules in the rulebook"""
+        return lcall(self.rules.values(), lambda x: x.applied_log, flatten=True)
+
+    @property
+    def _all_invoked_log(self):
+        """return all invoked logs from all rules in the rulebook"""
+        return lcall(self.rules.values(), lambda x: x.invoked_log, flatten=True)
+
+    def __getitem__(self, key: str) -> Rule:
+        return self.rules[key]
+
+    # def add_rule(self, rule_name: str, rule: Rule, config: dict = None):
+    #     if rule_name in self.rules:
+    #         raise ValueError(f"Rule '{rule_name}' already exists.")
+    #     self.rules[rule_name] = rule
+    #     self.ruleorder.append(rule_name)
+    #     self.rule_config[rule_name] = config or {}
+
+    # def remove_rule(self, rule_name: str):
+    #     if rule_name not in self.rules:
+    #         raise ValueError(f"Rule '{rule_name}' does not exist.")
+    #     del self.rules[rule_name]
+    #     self.ruleorder.remove(rule_name)
+    #     del self.rule_config[rule_name]
+
+    # def update_rule_config(self, rule_name: str, config: dict):
+    #     if rule_name not in self.rules:
+    #         raise ValueError(f"Rule '{rule_name}' does not exist.")
+    #     self.rule_config[rule_name] = config
+
+    # def list_rules(self) -> list[str]:
+    #     return self.ruleorder
+
+    # def get_rule_details(self, rule_name: str) -> dict:
+    #     if rule_name not in self.rules:
+    #         raise ValueError(f"Rule '{rule_name}' does not exist.")
+    #     return {
+    #         "rule": self.rules[rule_name],
+    #         "config": self.rule_config[rule_name]
+    #     }
+
+    # async def validate_data(self, data: Any) -> bool:
+    #     for rule in self.rules.values():
+    #         if not await rule.validate(data):
+    #             return False
+    #     return True
+
+    # def export_rulebook(self, filepath: str):
+    #     import json
+    #     with open(filepath, 'w') as f:
+    #         json.dump({
+    #             "rules": list(self.rules.keys()),
+    #             "ruleorder": self.ruleorder,
+    #             "rule_config": self.rule_config
+    #         }, f)
+
+    # @classmethod
+    # def import_rulebook(cls, filepath: str) -> 'RuleBook':
+    #     import json
+    #     with open(filepath, 'r') as f:
+    #         config = json.load(f)
+    #     rules = {name: Rule() for name in config["rules"]}
+    #     return cls(rules=rules, ruleorder=config["ruleorder"], rule_config=config["rule_config"])
+
+    # def enable_rule(self, rule_name: str, enable: bool = True):
+    #     if rule_name not in self.rules:
+    #         raise ValueError(f"Rule '{rule_name}' does not exist.")
+    #     self.rules[rule_name].enabled = enable
+
+    # def log_rule_application(self, rule_name: str, data: Any):
+    #     if rule_name not in self.rules:
+    #         raise ValueError(f"Rule '{rule_name}' does not exist.")
+    #     log_entry = {
+    #         "rule": rule_name,
+    #         "data": data,
+    #         "timestamp": SysUtil.get_timestamp()
+    #     }
+    #     # Append log_entry to a log file or a logging system

lionagi/core/rule/string.py

@@ -0,0 +1,52 @@
+from lionagi.libs.ln_convert import to_str
+from lionagi.core.rule.base import Rule
+
+
+class StringRule(Rule):
+    """
+    Rule for validating and converting string values.
+
+    Attributes:
+        fields (list[str]): The list of fields to which the rule applies.
+        apply_type (str): The type of data to which the rule applies.
+    """
+
+    fields: list[str] = ["reason", "prediction", "answer"]
+
+    def __init__(self, apply_type="str", **kwargs):
+        super().__init__(apply_type=apply_type, **kwargs)
+
+    async def validate(self, value):
+        """
+        Validate that the value is a string.
+
+        Args:
+            value: The value to validate.
+
+        Returns:
+            str: The validated string value.
+
+        Raises:
+            ValueError: If the value is not a string or is an empty string.
+        """
+        if isinstance(value, str) or value == "":
+            return value
+        raise ValueError(f"Invalid string field type.")
+
+    async def perform_fix(self, value):
+        """
+        Attempt to convert a value to a string.
+
+        Args:
+            value: The value to convert to a string.
+
+        Returns:
+            str: The value converted to a string.
+
+        Raises:
+            ValueError: If the value cannot be converted to a string.
+        """
+        try:
+            return to_str(value, **self.validation_kwargs)
+        except Exception as e:
+            raise ValueError(f"Failed to convert {value} into a string value") from e