fluxrules 0.1.0__py3-none-any.whl

fluxrules/__init__.py

@@ -0,0 +1,209 @@
+"""Public package interface for fluxrules core.
+
+Main API Functions:
+    evaluate() - Evaluate rules against facts
+    validate() - Validate rules
+    explain() - Get explanation for execution
+
+Every evaluation path returns the one :class:`EvaluationResult` type, whose
+``fired_rules`` holds the rules that matched::
+
+    from fluxrules import Rule, evaluate
+
+    rule = Rule(
+        name="adult",
+        condition_dsl={"type": "condition", "field": "age", "op": ">=", "value": 18},
+        action="allow",
+    )
+    evaluate(rule, {"age": 30}).fired_rules
+
+For engine implementations, import directly from their packages:
+    from fluxrules.engine.phreak import PhreakEngine
+
+Infrastructure:
+    from fluxrules.engine import BaseEngine
+"""
+
+from collections.abc import Iterable
+from typing import Any
+
+from fluxrules.config.deployment import (
+    ConfigValidationError,
+    DeploymentConfig,
+    DeploymentType,
+)
+from fluxrules.domain.errors import (
+    CorruptStoredRuleError,
+    CyclicDependencyError,
+    DSLValidationError,
+    EmptyRuleLogicError,
+    FluxRulesError,
+    InvalidRuleError,
+    LossyConditionRebuildError,
+    LossyConditionViewWarning,
+    UnknownOperatorError,
+)
+from fluxrules.domain.models import EngineRule as _EngineRule
+from fluxrules.domain.models import EvaluationResult, Ruleset
+from fluxrules.domain.rule_builder import ConditionBuilder, RuleBuilder
+from fluxrules.domain.unified_rule import Rule
+from fluxrules.engine import (
+    BaseEngine,
+    get_available_engines,
+    get_engine,
+    register_engine,
+    unregister_engine,
+)
+from fluxrules.engine.configuration import EngineConfig
+from fluxrules.engine.operator_registry import OperatorRegistry, register_operator
+from fluxrules.engine.phreak import PhreakEngine
+from fluxrules.initialization import (
+    initialize_fluxrules,
+    initialize_persistence,
+)
+from fluxrules.ports.persistence import RulePersistencePort
+from fluxrules.ports.validation import ValidationIssue, Validator
+from fluxrules.services.audit_service import AuditService
+from fluxrules.services.evaluation_service import EvaluationService
+from fluxrules.services.persistence_service import PersistenceService
+from fluxrules.services.rule_service import RuleService
+from fluxrules.services.validation_service import ValidationService
+from fluxrules.utils.id_generators import IDStrategy, RuleIDGenerator
+from fluxrules.version import __version__
+
+_DEFAULT_SERVICE = RuleService.create()
+
+
+#: What :func:`evaluate` and :func:`validate` accept: one rule, several rules,
+#: or an already-built :class:`Ruleset`.
+Rules = Ruleset | Rule | Iterable[Rule]
+
+
+def _coerce_facts(facts: object) -> dict[str, Any]:
+    """Return *facts* as a plain dict, accepting Pydantic models too."""
+    if isinstance(facts, dict):
+        return facts
+    if hasattr(facts, "model_dump"):  # Pydantic v2
+        return facts.model_dump()
+    if hasattr(facts, "dict"):  # Pydantic v1
+        return facts.dict()
+    raise TypeError(
+        f"facts must be a dict or a Pydantic model, got {type(facts).__name__}. "
+        "Convert your object to a dict first."
+    )
+
+
+def _as_ruleset(rules: Rules, *, group: str = "default") -> Ruleset:
+    """Normalise whatever the caller passed into a :class:`Ruleset`.
+
+    A ``Ruleset`` passes through. A single :class:`Rule` or an iterable of them
+    is converted here, so callers never have to reach for the internal
+    ``to_engine_rule()`` adapter just to evaluate a list of rules.
+    """
+    if isinstance(rules, Ruleset):
+        return rules
+    if isinstance(rules, Rule):
+        rules = [rules]
+
+    engine_rules: list[_EngineRule] = []
+    for rule in rules:
+        if isinstance(rule, Rule):
+            engine_rules.append(rule.to_engine_rule())
+        elif isinstance(rule, _EngineRule):
+            engine_rules.append(rule)
+        else:
+            raise TypeError(
+                "Expected a Rule, a Ruleset, or an iterable of Rules; got "
+                f"{type(rule).__name__}. Build rules with fluxrules.Rule(...) "
+                "or fluxrules.RuleBuilder."
+            )
+    return Ruleset(group=group, rules=tuple(engine_rules))
+
+
+def evaluate(rules: Rules, facts: object) -> EvaluationResult:
+    """Evaluate rules against a fact map with default in-memory services.
+
+    *rules* may be a single :class:`Rule`, any iterable of them, or a
+    :class:`Ruleset`::
+
+        rule = Rule(name="adult", condition_dsl={...}, action="allow")
+        result = evaluate(rule, {"age": 30})
+        result.fired_rules  # the rules that matched
+
+    *facts* may be a plain ``dict``, a Pydantic model, or any object with a
+    ``model_dump()`` / ``dict()`` method.
+
+    Returns:
+        An :class:`EvaluationResult` whose ``fired_rules`` lists what matched.
+    """
+    result = _DEFAULT_SERVICE.evaluate_inline(_as_ruleset(rules), _coerce_facts(facts))
+    _DEFAULT_SERVICE.execution_store.save(result)
+    return result
+
+
+def validate(rules: Rules) -> list[str]:
+    """Validate rules and return human-readable issues.
+
+    Accepts the same shapes as :func:`evaluate`. An empty list means valid.
+    """
+    return ValidationService().validate_ruleset(_as_ruleset(rules))
+
+
+def explain(execution_id: str) -> dict[str, object]:
+    """Return a transport-safe explanation payload for callers."""
+    execution_result = _DEFAULT_SERVICE.explain(execution_id)
+    return {
+        "execution_id": execution_result.execution_id,
+        "fired_rules": execution_result.fired_rules,
+        "actions": execution_result.actions,
+        "trace": execution_result.trace,
+    }
+
+
+__all__ = [
+    "AuditService",
+    "BaseEngine",
+    "ConditionBuilder",
+    "ConfigValidationError",
+    "CorruptStoredRuleError",
+    # Error taxonomy (see fluxrules.domain.errors). Every one derives from
+    # FluxRulesError, so `except FluxRulesError` catches the whole family.
+    "CyclicDependencyError",
+    "DSLValidationError",
+    "DeploymentConfig",
+    "DeploymentType",
+    "EmptyRuleLogicError",
+    "EngineConfig",
+    "EvaluationResult",
+    "EvaluationService",
+    "FluxRulesError",
+    "IDStrategy",
+    "InvalidRuleError",
+    "LossyConditionRebuildError",
+    "LossyConditionViewWarning",
+    "OperatorRegistry",
+    "PersistenceService",
+    "PhreakEngine",
+    "Rule",
+    "RuleBuilder",
+    "RuleIDGenerator",
+    "RulePersistencePort",
+    "RuleService",
+    "Rules",
+    "Ruleset",
+    "UnknownOperatorError",
+    "ValidationIssue",
+    "ValidationService",
+    "Validator",
+    "__version__",
+    "evaluate",
+    "explain",
+    "get_available_engines",
+    "get_engine",
+    "initialize_fluxrules",
+    "initialize_persistence",
+    "register_engine",
+    "register_operator",
+    "unregister_engine",
+    "validate",
+]

fluxrules/adapters/__init__.py

@@ -0,0 +1,3 @@
+"""Adapter implementations (concrete strategy classes)."""
+
+__all__ = []

fluxrules/adapters/caches/__init__.py

@@ -0,0 +1,100 @@
+"""In-memory rule cache adapter for testing and embedded mode."""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+from fluxrules.ports.rule_cache import RuleCachePort
+
+
+class InMemoryRuleCacheAdapter(RuleCachePort):
+    """In-memory LRU-style cache for compiled rule networks.
+
+    Supports TTL-based expiration. Suitable for testing and single-process mode.
+    """
+
+    def __init__(self, max_size: int = 1000) -> None:
+        self._cache: dict[str, tuple[Any, float]] = {}  # key -> (value, expire_time)
+        self._max_size = max_size
+        self._stats = {"hits": 0, "misses": 0}
+        self._closed = False
+
+    def _make_key(self, ruleset_id: int, version: int) -> str:
+        return f"{ruleset_id}:{version}"
+
+    def get(self, ruleset_id: int, version: int) -> Any | None:
+        """Get compiled rule network from cache."""
+        if self._closed:
+            return None
+
+        key = self._make_key(ruleset_id, version)
+        entry = self._cache.get(key)
+
+        if entry is None:
+            self._stats["misses"] += 1
+            return None
+
+        value, expire_time = entry
+        if time.time() > expire_time:
+            del self._cache[key]
+            self._stats["misses"] += 1
+            return None
+
+        self._stats["hits"] += 1
+        return value
+
+    def set(
+        self,
+        ruleset_id: int,
+        version: int,
+        network: Any,
+        ttl_seconds: int = 3600,
+    ) -> None:
+        """Store compiled rule network with TTL."""
+        if self._closed:
+            return
+
+        # Evict oldest if at capacity
+        if len(self._cache) >= self._max_size:
+            oldest_key = next(iter(self._cache))
+            del self._cache[oldest_key]
+
+        key = self._make_key(ruleset_id, version)
+        self._cache[key] = (network, time.time() + ttl_seconds)
+
+    def invalidate(self, ruleset_id: int) -> None:
+        """Invalidate all versions of a ruleset."""
+        prefix = f"{ruleset_id}:"
+        keys_to_delete = [k for k in self._cache if k.startswith(prefix)]
+        for key in keys_to_delete:
+            del self._cache[key]
+
+    def get_stats(self) -> dict[str, Any]:
+        """Return cache statistics."""
+        total = self._stats["hits"] + self._stats["misses"]
+        hit_rate = self._stats["hits"] / total if total > 0 else 0.0
+        return {
+            "hits": self._stats["hits"],
+            "misses": self._stats["misses"],
+            "hit_rate": hit_rate,
+            "size": len(self._cache),
+            "max_size": self._max_size,
+        }
+
+    def health_check(self) -> tuple[bool, str]:
+        """Always healthy for in-memory."""
+        if self._closed:
+            return False, "Cache adapter is closed"
+        return True, "In-memory cache is healthy"
+
+    def close(self) -> None:
+        """Mark as closed."""
+        self._closed = True
+        self._cache.clear()
+
+    def reset(self) -> None:
+        """Reset all state (for testing)."""
+        self._cache.clear()
+        self._stats = {"hits": 0, "misses": 0}
+        self._closed = False

fluxrules/adapters/loaders/__init__.py

@@ -0,0 +1,5 @@
+"""Loaders package - YAML and other rule source adapters."""
+
+from fluxrules.adapters.loaders.yaml_loader import load_rules_from_yaml
+
+__all__ = ["load_rules_from_yaml"]

fluxrules/adapters/loaders/yaml_loader.py

@@ -0,0 +1,47 @@
+"""YAML rule loader - load rules from a YAML file.
+
+YAML schema: a list of rule mappings (or a single mapping) with the same
+schema as the JSON/dict format used by ``RuleEngine.add_rules()``.
+
+Requires: ``pip install pyyaml``
+
+Example YAML::
+
+    - id: 1
+      name: high_value
+      priority: 10
+      action: flag_for_review
+      enabled: true
+      condition_dsl:
+        type: condition
+        field: amount
+        op: ">"
+        value: 1000
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def load_rules_from_yaml(path: str) -> list[dict[str, Any]]:
+    """Load rules from a YAML file.
+
+    Args:
+        path: Path to the YAML file.
+
+    Returns:
+        A list of rule dicts ready to pass to ``RuleEngine.add_rules()``.
+
+    Raises:
+        ImportError: When ``pyyaml`` is not installed.
+    """
+    try:
+        import yaml  # type: ignore[import]
+    except ImportError as exc:
+        raise ImportError(
+            "pyyaml is required for YAML rule loading. Install it with: pip install pyyaml"
+        ) from exc
+    with open(path) as f:
+        rules = yaml.safe_load(f)
+    return rules if isinstance(rules, list) else [rules]

fluxrules/adapters/observability/__init__.py

@@ -0,0 +1,3 @@
+"""Observability adapter implementations."""
+
+__all__ = ["NoopTracer"]

fluxrules/adapters/observability/noop.py

@@ -0,0 +1,27 @@
+"""No-operation tracer for when observability is not needed."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fluxrules.ports.observability import TracerPort
+
+
+class NoopTracer(TracerPort):
+    """A no-op tracer that discards all tracing data."""
+
+    def on_evaluation_start(self, ruleset_id: int | str) -> None:
+        """Called at the start of ruleset evaluation (no-op)."""
+
+    def on_evaluation_end(self, ruleset_id: int | str, matched_count: int) -> None:
+        """Called at the end of ruleset evaluation (no-op)."""
+
+    def start_span(self, name: str, attributes: dict[str, Any] | None = None) -> Any:
+        """Start a span (no-op)."""
+        return None
+
+    def end_span(self, span: Any) -> None:
+        """End a span (no-op)."""
+
+    def record_event(self, span: Any, name: str, attributes: dict[str, Any] | None = None) -> None:
+        """Record an event (no-op)."""

fluxrules/adapters/persistence/__init__.py

@@ -0,0 +1,7 @@
+"""SQLAlchemy persistence adapter - isolates ORM imports from core."""
+
+from fluxrules.adapters.persistence.sqlalchemy_adapter import (
+    SQLAlchemyPersistenceAdapter,
+)
+
+__all__ = ["SQLAlchemyPersistenceAdapter"]

fluxrules/adapters/persistence/sqlalchemy_adapter.py

@@ -0,0 +1,168 @@
+"""SQLAlchemy-backed persistence adapter.
+
+Isolates all ORM imports (fluxrules.api.models.*) to this adapter layer,
+keeping the core and services layers free of database coupling.
+
+Supports two construction modes:
+
+1. **Lazy session binding** (preferred for DI / ServiceFactory)::
+
+       adapter = SQLAlchemyPersistenceAdapter(
+           session_provider=lambda: SessionLocal(),
+       )
+
+   The *session_provider* callable is invoked each time a database
+   session is needed, enabling request-scoped session management in
+   web frameworks like FastAPI.
+
+2. **Direct session** (legacy / simple scripts)::
+
+       adapter = SQLAlchemyPersistenceAdapter(db=my_session)
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+from datetime import datetime, timezone
+
+from sqlalchemy.orm import Session
+
+from fluxrules.domain.models import EngineRule, Ruleset
+from fluxrules.persistence.mappers import domain_rule_to_orm, orm_rule_to_domain
+from fluxrules.ports.persistence import RulePersistencePort
+
+logger = logging.getLogger("fluxrules.adapters.persistence")
+
+
+class SQLAlchemyPersistenceAdapter(RulePersistencePort):
+    """Concrete persistence implementation using SQLAlchemy ORM.
+
+    All ORM model imports are isolated here, so the core engine
+    and services never depend on the API/database layer directly.
+
+    Args:
+        db: A pre-existing SQLAlchemy session (legacy mode).
+        session_provider: A callable returning a SQLAlchemy ``Session``.
+            When provided, the adapter calls it each time it needs a
+            session.  This enables **lazy session binding** - the
+            recommended pattern for ServiceFactory / DI usage.
+
+    Raises:
+        ValueError: If neither *db* nor *session_provider* is given.
+    """
+
+    def __init__(
+        self,
+        db: Session | None = None,
+        *,
+        session_provider: Callable[[], Session] | None = None,
+    ) -> None:
+        if db is None and session_provider is None:
+            raise ValueError(
+                "SQLAlchemyPersistenceAdapter requires either 'db' "
+                "(a Session) or 'session_provider' (a callable)"
+            )
+        self._db = db
+        self._session_provider = session_provider
+
+    @property
+    def db(self) -> Session:
+        """Return the active database session.
+
+        When a *session_provider* was supplied at construction time the
+        provider is called each time this property is accessed, enabling
+        request-scoped or lazy session semantics.
+        """
+        if self._session_provider is not None:
+            return self._session_provider()
+        assert self._db is not None
+        return self._db
+
+    # ── Write operations ─────────────────────────────────────────────────────
+
+    def save_rule(self, rule: EngineRule, group: str = "", created_by: int | None = None) -> int:
+        orm_rule = domain_rule_to_orm(rule, group=group, created_by=created_by)
+        self.db.add(orm_rule)
+        self.db.commit()
+        self.db.refresh(orm_rule)
+        return orm_rule.id
+
+    def save_ruleset(self, ruleset: Ruleset, created_by: int | None = None) -> list[int]:
+        ids: list[int] = []
+        for rule in ruleset.rules:
+            rid = self.save_rule(rule, group=ruleset.group, created_by=created_by)
+            ids.append(rid)
+        return ids
+
+    def update_rule(self, rule_id: int, **kwargs) -> EngineRule | None:
+        from fluxrules.api.models.rule import Rule as OrmRule
+
+        orm_rule = self.db.query(OrmRule).filter(OrmRule.id == rule_id).first()
+        if orm_rule is None:
+            return None
+
+        for key, value in kwargs.items():
+            if key == "conditions" and isinstance(value, (list, tuple)):
+                # Store a DSL tree, not a list of condition dicts: the column
+                # holds exactly one shape.
+                from fluxrules.domain.dsl.evaluator import conditions_to_dsl
+
+                orm_rule.condition_dsl = conditions_to_dsl(value)
+            elif key == "condition_dsl":
+                orm_rule.condition_dsl = value
+            elif key == "actions" and isinstance(value, (list, tuple)):
+                orm_rule.action = "\n".join(value)
+            elif hasattr(orm_rule, key):
+                setattr(orm_rule, key, value)
+
+        orm_rule.updated_at = datetime.now(timezone.utc)
+        self.db.commit()
+        self.db.refresh(orm_rule)
+        return orm_rule_to_domain(orm_rule)
+
+    def delete_rule(self, rule_id: int) -> bool:
+        from fluxrules.api.models.rule import Rule as OrmRule
+
+        orm_rule = self.db.query(OrmRule).filter(OrmRule.id == rule_id).first()
+        if orm_rule is None:
+            return False
+        self.db.delete(orm_rule)
+        self.db.commit()
+        return True
+
+    # ── Read operations ──────────────────────────────────────────────────────
+
+    def load_rule(self, rule_id: int) -> EngineRule | None:
+        from fluxrules.api.models.rule import Rule as OrmRule
+
+        orm_rule = self.db.query(OrmRule).filter(OrmRule.id == rule_id).first()
+        if orm_rule is None:
+            return None
+        return orm_rule_to_domain(orm_rule)
+
+    def load_all_rules(self) -> list[EngineRule]:
+        from fluxrules.api.models.rule import Rule as OrmRule
+
+        orm_rules = self.db.query(OrmRule).order_by(OrmRule.priority.desc()).all()
+        return [orm_rule_to_domain(r) for r in orm_rules]
+
+    def load_ruleset(self, group: str) -> Ruleset:
+        from fluxrules.api.models.rule import Rule as OrmRule
+
+        orm_rules = (
+            self.db.query(OrmRule)
+            .filter(OrmRule.group == group)
+            .order_by(OrmRule.priority.desc())
+            .all()
+        )
+        rules = [orm_rule_to_domain(r) for r in orm_rules]
+        return Ruleset(group=group, rules=tuple(rules))
+
+    def load_all_rulesets(self) -> dict[str, Ruleset]:
+        all_rules = self.load_all_rules()
+        groups: dict[str, list[EngineRule]] = {}
+        for r in all_rules:
+            g = r.group or ""
+            groups.setdefault(g, []).append(r)
+        return {g: Ruleset(group=g, rules=tuple(rs)) for g, rs in groups.items()}

fluxrules/adapters/queues/__init__.py

@@ -0,0 +1,101 @@
+"""In-memory queue adapter for testing and embedded mode."""
+
+from __future__ import annotations
+
+import uuid
+from collections import defaultdict
+from datetime import datetime, timezone
+from typing import Any
+
+from fluxrules.ports.queue import QueuePort
+
+
+class InMemoryQueueAdapter(QueuePort):
+    """In-memory queue implementation for testing and single-process mode.
+
+    Thread-safe for single-process usage. Does not persist across restarts.
+    """
+
+    def __init__(self) -> None:
+        self._topics: dict[str, list[dict[str, Any]]] = defaultdict(list)
+        self._offsets: dict[str, dict[str, int]] = defaultdict(lambda: defaultdict(int))
+        self._closed = False
+
+    def enqueue(
+        self,
+        topic: str,
+        partition_key: str,
+        message: dict[str, Any],
+        priority: int = 0,
+    ) -> str:
+        """Enqueue a message to a topic."""
+        if self._closed:
+            raise RuntimeError("Queue adapter is closed")
+
+        message_id = str(uuid.uuid4())
+        enriched = {
+            "id": message_id,
+            "type": message.get("type", "unknown"),
+            "payload": message.get("payload", {}),
+            "source": message.get("source", "api"),
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "priority": priority,
+            "partition_key": partition_key,
+            "retry_count": 0,
+        }
+        self._topics[topic].append(enriched)
+        return message_id
+
+    def dequeue(
+        self,
+        topic: str,
+        consumer_group: str,
+        timeout_ms: int = 1000,
+    ) -> list[dict[str, Any]]:
+        """Dequeue messages from a topic."""
+        if self._closed:
+            raise RuntimeError("Queue adapter is closed")
+
+        current_offset = self._offsets[topic][consumer_group]
+        messages = self._topics[topic][current_offset:]
+
+        result = []
+        for i, msg in enumerate(messages):
+            result.append(
+                {
+                    "payload": msg,
+                    "topic": topic,
+                    "partition": 0,
+                    "offset": current_offset + i,
+                    "timestamp": msg["timestamp"],
+                }
+            )
+
+        return result
+
+    def commit_offset(self, topic: str, partition: int, offset: int, consumer_group: str) -> None:
+        """Commit offset after successful processing."""
+        self._offsets[topic][consumer_group] = offset + 1
+
+    def peek(self, topic: str, partition: int, offset: int) -> dict[str, Any] | None:
+        """Peek at a message without consuming."""
+        messages = self._topics.get(topic, [])
+        if 0 <= offset < len(messages):
+            return messages[offset]
+        return None
+
+    def health_check(self) -> tuple[bool, str]:
+        """Always healthy for in-memory."""
+        if self._closed:
+            return False, "Queue adapter is closed"
+        return True, "In-memory queue is healthy"
+
+    def close(self) -> None:
+        """Mark as closed."""
+        self._closed = True
+
+    def reset(self) -> None:
+        """Reset all state (for testing)."""
+        self._topics.clear()
+        self._offsets.clear()
+        self._closed = False

fluxrules/adapters/repository/__init__.py

@@ -0,0 +1,15 @@
+"""Repository adapter implementations."""
+
+from fluxrules.adapters.repository.database import (
+    DatabaseRulesetRepository,
+)
+from fluxrules.adapters.repository.in_memory import (
+    InMemoryExecutionStore,
+    InMemoryRulesetRepository,
+)
+
+__all__ = [
+    "DatabaseRulesetRepository",
+    "InMemoryExecutionStore",
+    "InMemoryRulesetRepository",
+]