Adds RuleBook serialization (JSON/YAML) (#1)

* Adds RuleBook serialization (JSON/YAML)

Adds serialization support for rule books, enabling export/import as dict, JSON, and optional YAML with schema versioning and validation to support safe persistence and future migrations.

Exposes canonical dict-based API with validation by default and convenience JSON/YAML helpers; JSON is always available while YAML is optional via an extra dependency and emits a clear serialization error when missing. Introduces explicit serialization/validation/version error classes and preserves rule source to improve round‑tripping and diagnostics.

Updates packaging metadata to declare the optional YAML dependency.

* Improve typing and validate inline rule sources

Author: joaofreires

README.md

@@ -9,6 +9,7 @@ A tiny, safe **boolean expression** engine: like Jinja for logic.
 - **RuleBook**: name your rules and evaluate them later
 - **RuleGroup**: compose rules with `all`/`any` semantics and nested groups
 - **Missing policy**: choose to **raise** or substitute **None/False/custom default**
+- **Serialization**: export/import rule books as JSON or (optionally) YAML
 
 ```py
 from boolia import evaluate, RuleBook, DEFAULT_FUNCTIONS
@@ -146,6 +147,34 @@ print(rules.evaluate("eligible", context={"user": {"age": 17, "country": "Chile"
 
 `RuleGroup` members can be rule names, already compiled `Rule` objects, or other `RuleGroup` instances. Nested groups short-circuit according to their mode (`all`/`any`), empty groups are vacuously `True`/`False`, and cycles raise a helpful error. Add groups with `RuleBook.add_group` or register existing ones with `RuleBook.register`.
 
+#### RuleBook serialization
+
+```py
+from boolia import RuleBook
+
+rules = RuleBook()
+rules.add("adult", "user.age >= 18")
+rules.add_group("gate", members=["adult"])
+
+payload = rules.to_dict()
+clone = RuleBook.from_dict(payload)
+assert clone.evaluate("gate", context={"user": {"age": 21}})
+
+json_blob = rules.to_json(indent=2)
+loaded = RuleBook.from_json(json_blob)
+
+# Optional YAML helpers (requires: pip install boolia[yaml])
+yaml_blob = rules.to_yaml()
+RuleBook.from_yaml(yaml_blob)
+```
+
+- `RuleBook.to_dict` / `RuleBook.from_dict` are the canonical API and perform schema validation by default.
+- `to_json` / `from_json` are always available via the standard library.
+- `to_yaml` / `from_yaml` lazily import PyYAML; missing dependencies raise a clear `RulebookSerializationError`.
+- Pass custom JSON encoders/decoders (e.g. `orjson.dumps`) via the `encoder=` / `decoder=` keyword arguments.
+
+Payloads include a schema version to enable future migrations. Inline rules or groups are supported when importing by default; pass `allow_inline=False` to reject them.
+
 ### Missing policy
 
 ```py

boolia/__init__.py

@@ -9,7 +9,12 @@
     RuleGroup,
 )
 from .resolver import default_resolver_factory, MissingPolicy
-from .errors import MissingVariableError
+from .errors import (
+    MissingVariableError,
+    RulebookSerializationError,
+    RulebookValidationError,
+    RulebookVersionError,
+)
 from .functions import FunctionRegistry, DEFAULT_FUNCTIONS
 from .operators import OperatorRegistry, DEFAULT_OPERATORS
 
@@ -25,6 +30,9 @@
     "default_resolver_factory",
     "MissingPolicy",
     "MissingVariableError",
+    "RulebookSerializationError",
+    "RulebookValidationError",
+    "RulebookVersionError",
     "FunctionRegistry",
     "DEFAULT_FUNCTIONS",
     "OperatorRegistry",

boolia/api.py

@@ -2,6 +2,15 @@
 from dataclasses import dataclass
 from typing import Any, Callable, Dict, Iterable, Literal, Optional, Set, Union
 
+from .serialization import (
+    rulebook_from_dict,
+    rulebook_from_json,
+    rulebook_from_yaml,
+    rulebook_to_dict,
+    rulebook_to_json,
+    rulebook_to_yaml,
+)
+
 from .parser import parse
 from .ast import Node
 from .resolver import default_resolver_factory, MissingPolicy
@@ -42,6 +51,7 @@ def evaluate(
 class Rule:
     ast: Node
     operators: OperatorRegistry = DEFAULT_OPERATORS
+    source: Optional[str] = None
 
     def evaluate(self, *, operators: Optional[OperatorRegistry] = None, **kwargs) -> bool:
         local_kwargs = kwargs.copy()
@@ -52,7 +62,7 @@ def evaluate(self, *, operators: Optional[OperatorRegistry] = None, **kwargs) ->
 
 def compile_rule(source: str, *, operators: Optional[OperatorRegistry] = None) -> Rule:
     ops = operators or DEFAULT_OPERATORS
-    return Rule(compile_expr(source, operators=ops), ops)
+    return Rule(compile_expr(source, operators=ops), ops, source)
 
 
 class RuleGroup:
@@ -192,3 +202,74 @@ def _store(self, name: str, rule: RuleEntry) -> None:
         self._rules[name] = rule
         if isinstance(rule, RuleGroup):
             rule.bind_lookup(self.get)
+
+    def to_dict(
+        self,
+        *,
+        version: str = "1.0",
+        include_metadata: bool = True,
+        validate: bool = True,
+    ) -> Dict[str, Any]:
+        return rulebook_to_dict(
+            self,
+            version=version,
+            include_metadata=include_metadata,
+            validate=validate,
+        )
+
+    @classmethod
+    def from_dict(
+        cls,
+        payload: Dict[str, Any],
+        *,
+        validate: bool = True,
+        allow_inline: bool = True,
+    ) -> "RuleBook":
+        return rulebook_from_dict(
+            cls,
+            payload,
+            validate=validate,
+            allow_inline=allow_inline,
+        )
+
+    def to_json(self, target=None, *, encoder=None, **json_kwargs):
+        return rulebook_to_json(self, target=target, encoder=encoder, **json_kwargs)
+
+    @classmethod
+    def from_json(
+        cls,
+        source,
+        *,
+        validate: bool = True,
+        allow_inline: bool = True,
+        decoder=None,
+        **json_kwargs,
+    ) -> "RuleBook":
+        return rulebook_from_json(
+            cls,
+            source,
+            validate=validate,
+            allow_inline=allow_inline,
+            decoder=decoder,
+            **json_kwargs,
+        )
+
+    def to_yaml(self, target=None, **yaml_kwargs):
+        return rulebook_to_yaml(self, target=target, **yaml_kwargs)
+
+    @classmethod
+    def from_yaml(
+        cls,
+        source,
+        *,
+        validate: bool = True,
+        allow_inline: bool = True,
+        **yaml_kwargs,
+    ) -> "RuleBook":
+        return rulebook_from_yaml(
+            cls,
+            source,
+            validate=validate,
+            allow_inline=allow_inline,
+            **yaml_kwargs,
+        )

boolia/errors.py

@@ -4,3 +4,19 @@ class MissingVariableError(NameError):
     def __init__(self, parts):
         super().__init__(f"Missing variable/path: {'.'.join(parts)}")
         self.parts = parts
+
+
+class RulebookError(Exception):
+    """Base class for rulebook serialization errors."""
+
+
+class RulebookSerializationError(RulebookError):
+    """Raised when serialization fails (e.g. missing dependencies)."""
+
+
+class RulebookValidationError(RulebookError):
+    """Raised when a serialized payload does not match the expected schema."""
+
+
+class RulebookVersionError(RulebookError):
+    """Raised when a serialized payload uses an unsupported schema version."""