fast-feature-engine 0.0.1__tar.gz

fast_feature_engine-0.0.1/PKG-INFO

@@ -0,0 +1,19 @@
+Metadata-Version: 2.4
+Name: fast-feature-engine
+Version: 0.0.1
+Summary: JsonLogic targeting and evaluation engine for fast-feature.
+Author: byunjuneseok
+Author-email: byunjuneseok <byunjuneseok@gmail.com>
+License-Expression: Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Dist: fast-feature-core==0.0.1
+Requires-Dist: mmh3>=4.0
+Requires-Python: >=3.10

fast_feature_engine-0.0.1/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "fast-feature-engine"
+version = "0.0.1"
+description = "JsonLogic targeting and evaluation engine for fast-feature."
+license = "Apache-2.0"
+requires-python = ">=3.10"
+authors = [
+    { name = "byunjuneseok", email = "byunjuneseok@gmail.com" },
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "fast-feature-core==0.0.1",
+    "mmh3>=4.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.17,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "fast_feature.engine"
+
+[tool.uv.sources]
+fast-feature-core = { workspace = true }

fast_feature_engine-0.0.1/src/fast_feature/engine/__init__.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from .coercion import Coercion
+from .engine import TargetingEngine
+from .errors import EngineError, JsonLogicError
+from .evaluator import JsonLogicEvaluator
+from .hashing import Hasher, Murmur3Hasher
+from .operator import Operator, SimpleOperator
+from .operators import StandardOperators, TargetingOperators
+from .registry import OperatorRegistry
+from .semver import SemanticVersion
+
+__all__ = [
+    "TargetingEngine",
+    "JsonLogicEvaluator",
+    "OperatorRegistry",
+    "Operator",
+    "SimpleOperator",
+    "Coercion",
+    "Hasher",
+    "Murmur3Hasher",
+    "SemanticVersion",
+    "StandardOperators",
+    "TargetingOperators",
+    "EngineError",
+    "JsonLogicError",
+]

fast_feature_engine-0.0.1/src/fast_feature/engine/coercion/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from .coercion import Coercion
+
+__all__ = ["Coercion"]

fast_feature_engine-0.0.1/src/fast_feature/engine/coercion/coercion.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from typing import Any
+
+from fast_feature.engine.errors import JsonLogicError
+
+
+class Coercion:
+    """JavaScript-aligned type coercion shared by the operators."""
+
+    @staticmethod
+    def is_truthy(value: Any) -> bool:
+        if value is None or value is False:
+            return False
+        if isinstance(value, bool):
+            return value
+        if isinstance(value, int | float):
+            return value != 0
+        if isinstance(value, str):
+            return value != ""
+        if isinstance(value, list):
+            return len(value) > 0
+        if isinstance(value, dict):
+            return True
+        return bool(value)
+
+    @staticmethod
+    def to_str(value: Any) -> str:
+        if value is None:
+            return ""
+        if value is True:
+            return "true"
+        if value is False:
+            return "false"
+        return str(value)
+
+    @staticmethod
+    def to_number(value: Any) -> float:
+        if isinstance(value, bool):
+            return int(value)
+        if isinstance(value, int | float):
+            return value
+        if isinstance(value, str):
+            try:
+                if any(c in value for c in ".eE"):
+                    return float(value)
+                return int(value)
+            except ValueError as exc:
+                raise JsonLogicError(f"cannot convert {value!r} to a number") from exc
+        raise JsonLogicError(f"cannot convert {value!r} to a number")
+
+    @classmethod
+    def soft_equals(cls, a: Any, b: Any) -> bool:
+        if isinstance(a, bool) or isinstance(b, bool):
+            return cls.is_truthy(a) is cls.is_truthy(b)
+        if isinstance(a, str) or isinstance(b, str):
+            return cls.to_str(a) == cls.to_str(b)
+        return bool(a == b)
+
+    @staticmethod
+    def hard_equals(a: Any, b: Any) -> bool:
+        if type(a) is not type(b):
+            return False
+        return bool(a == b)
+
+    @classmethod
+    def less_than(cls, a: Any, b: Any) -> bool:
+        if isinstance(a, str) and isinstance(b, str):
+            return a < b
+        return cls.to_number(a) < cls.to_number(b)
+
+    @classmethod
+    def less_than_or_equal(cls, a: Any, b: Any) -> bool:
+        if isinstance(a, str) and isinstance(b, str):
+            return a <= b
+        return cls.to_number(a) <= cls.to_number(b)

fast_feature_engine-0.0.1/src/fast_feature/engine/engine.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+from fast_feature.core.evaluation import ErrorCode, EvaluationOutcome, Reason
+from fast_feature.core.flag import Flag, FlagState
+from fast_feature.core.types import EvaluationContext, JsonValue
+
+from .errors import JsonLogicError
+from .evaluator import JsonLogicEvaluator
+from .hashing import Hasher, Murmur3Hasher
+from .operators import StandardOperators, TargetingOperators
+from .registry import OperatorRegistry
+
+
+class TargetingEngine:
+    """Resolves a flag against a context using the following evaluation semantics.
+
+    - ``DISABLED`` flag                  -> reason ``DISABLED``
+    - no targeting rule                  -> reason ``STATIC``
+    - targeting returns a known variant  -> reason ``TARGETING_MATCH``
+    - targeting returns ``null``         -> reason ``DEFAULT``
+    - targeting errors / unknown variant -> reason ``ERROR`` (``PARSE_ERROR``)
+
+    In every non-match case the flag's default variant value is returned, so a
+    caller always receives a usable value.
+    """
+
+    def __init__(self, hasher: Hasher | None = None) -> None:
+        registry = OperatorRegistry(StandardOperators.mapping()).extended_with(
+            TargetingOperators.mapping(hasher or Murmur3Hasher())
+        )
+        self._evaluator = JsonLogicEvaluator(registry)
+
+    def evaluate(self, flag: Flag, context: EvaluationContext | None = None) -> EvaluationOutcome:
+        if flag.state is FlagState.DISABLED:
+            return self._resolved(flag, flag.default_variant, Reason.DISABLED)
+
+        if not flag.targeting:
+            return self._resolved(flag, flag.default_variant, Reason.STATIC)
+
+        try:
+            result = self._evaluator.apply(flag.targeting, self._build_data(flag, context))
+        except JsonLogicError as exc:
+            return self._errored(flag, str(exc))
+
+        if result is None:
+            return self._resolved(flag, flag.default_variant, Reason.DEFAULT)
+        if not isinstance(result, str) or not flag.has_variant(result):
+            return self._errored(
+                flag, f"targeting resolved to {result!r}, which is not a defined variant"
+            )
+        return self._resolved(flag, result, Reason.TARGETING_MATCH)
+
+    @staticmethod
+    def _build_data(flag: Flag, context: EvaluationContext | None) -> dict[str, JsonValue]:
+        data: dict[str, JsonValue] = dict(context or {})
+        data["$flag"] = {"key": flag.key}
+        return data
+
+    @staticmethod
+    def _resolved(flag: Flag, variant: str, reason: Reason) -> EvaluationOutcome:
+        return EvaluationOutcome(
+            key=flag.key,
+            reason=reason,
+            value=flag.value_of(variant),
+            variant=variant,
+            metadata=flag.metadata or None,
+        )
+
+    @staticmethod
+    def _errored(flag: Flag, details: str) -> EvaluationOutcome:
+        return EvaluationOutcome(
+            key=flag.key,
+            reason=Reason.ERROR,
+            value=flag.default_value,
+            variant=flag.default_variant,
+            metadata=flag.metadata or None,
+            error_code=ErrorCode.PARSE_ERROR,
+            error_details=details,
+        )

fast_feature_engine-0.0.1/src/fast_feature/engine/errors/__init__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from .base import EngineError
+from .json_logic import JsonLogicError
+
+__all__ = ["EngineError", "JsonLogicError"]

fast_feature_engine-0.0.1/src/fast_feature/engine/errors/base.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+
+class EngineError(Exception):
+    """Base class for all targeting-engine errors.
+
+    Dependents catch this at their boundary and re-raise as their own base
+    error (with chaining) rather than coupling to the concrete subclasses.
+    """

fast_feature_engine-0.0.1/src/fast_feature/engine/errors/json_logic.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from .base import EngineError
+
+
+class JsonLogicError(EngineError):
+    """Raised when a rule is malformed or cannot be evaluated."""

fast_feature_engine-0.0.1/src/fast_feature/engine/evaluator/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from .evaluator import JsonLogicEvaluator
+
+__all__ = ["JsonLogicEvaluator"]

fast_feature_engine-0.0.1/src/fast_feature/engine/evaluator/evaluator.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from typing import Any
+
+from fast_feature.engine.errors import JsonLogicError
+from fast_feature.engine.registry import OperatorRegistry
+
+
+class JsonLogicEvaluator:
+    """Evaluates a JsonLogic rule against a data object using a registry."""
+
+    def __init__(self, registry: OperatorRegistry) -> None:
+        self._registry = registry
+
+    def apply(self, rule: Any, data: Any = None) -> Any:
+        if data is None:
+            data = {}
+        if isinstance(rule, list):
+            return [self.apply(item, data) for item in rule]
+        if not self._is_operation(rule):
+            return rule
+        name, raw = next(iter(rule.items()))
+        args = raw if isinstance(raw, list) else [raw]
+        operator = self._registry.resolve(name)
+        if operator is None:
+            raise JsonLogicError(f"Unrecognized operation {name!r}")
+        return operator.apply(self, args, data)
+
+    @staticmethod
+    def _is_operation(rule: Any) -> bool:
+        return isinstance(rule, dict) and len(rule) == 1 and isinstance(next(iter(rule)), str)

fast_feature_engine-0.0.1/src/fast_feature/engine/hashing/__init__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from .hasher import Hasher
+from .murmur3_hasher import Murmur3Hasher
+
+__all__ = ["Hasher", "Murmur3Hasher"]

fast_feature_engine-0.0.1/src/fast_feature/engine/hashing/hasher.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class Hasher(Protocol):
+    """A deterministic hash used for ``fractional`` bucketing."""
+
+    @property
+    def max_value(self) -> int:
+        """The largest value ``hash`` can return (used to normalise to a ratio)."""
+
+    def hash(self, key: str) -> int: ...

fast_feature_engine-0.0.1/src/fast_feature/engine/hashing/murmur3_hasher.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+import mmh3
+
+
+class Murmur3Hasher:
+    """MurmurHash3 (x86, 32-bit) hasher backed by the ``mmh3`` library."""
+
+    @property
+    def max_value(self) -> int:
+        return 0xFFFFFFFF
+
+    def hash(self, key: str) -> int:
+        return mmh3.hash(key, signed=False)

fast_feature_engine-0.0.1/src/fast_feature/engine/operator/__init__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from .operator import Operator
+from .simple_operator import SimpleOperator
+
+__all__ = ["Operator", "SimpleOperator"]

fast_feature_engine-0.0.1/src/fast_feature/engine/operator/operator.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from fast_feature.engine.evaluator import JsonLogicEvaluator
+
+
+class Operator(ABC):
+    """A JsonLogic operation.
+
+    The operator owns how its arguments are evaluated, so control-flow
+    operators (``if``, ``and``, iterators, ...) can evaluate lazily.
+    """
+
+    @abstractmethod
+    def apply(self, evaluator: JsonLogicEvaluator, args: list[Any], data: Any) -> Any:
+        """Evaluate this operation's ``args`` against ``data``."""

fast_feature_engine-0.0.1/src/fast_feature/engine/operator/simple_operator.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from abc import abstractmethod
+from typing import TYPE_CHECKING, Any
+
+from .operator import Operator
+
+if TYPE_CHECKING:
+    from fast_feature.engine.evaluator import JsonLogicEvaluator
+
+
+class SimpleOperator(Operator):
+    """An operator whose arguments are all eagerly evaluated before computing."""
+
+    def apply(self, evaluator: JsonLogicEvaluator, args: list[Any], data: Any) -> Any:
+        return self.compute(*[evaluator.apply(arg, data) for arg in args])
+
+    @abstractmethod
+    def compute(self, *values: Any) -> Any:
+        """Compute the result from already-evaluated argument ``values``."""

fast_feature_engine-0.0.1/src/fast_feature/engine/operators/__init__.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+from fast_feature.engine.hashing import Hasher
+from fast_feature.engine.operator import Operator
+
+from .arithmetic import (
+    AddOperator,
+    DivideOperator,
+    MaxOperator,
+    MinOperator,
+    ModuloOperator,
+    MultiplyOperator,
+    SubtractOperator,
+)
+from .collection import (
+    AllOperator,
+    CatOperator,
+    FilterOperator,
+    InOperator,
+    MapOperator,
+    MergeOperator,
+    NoneMatchOperator,
+    ReduceOperator,
+    SomeOperator,
+    SubstrOperator,
+)
+from .comparison import (
+    EqualsOperator,
+    GreaterThanOperator,
+    GreaterThanOrEqualOperator,
+    LessThanOperator,
+    LessThanOrEqualOperator,
+    NotEqualsOperator,
+    StrictEqualsOperator,
+    StrictNotEqualsOperator,
+)
+from .data import MissingOperator, MissingSomeOperator, VarOperator
+from .logic import AndOperator, IfOperator, NotOperator, OrOperator, ToBoolOperator
+from .targeting import (
+    EndsWithOperator,
+    FractionalOperator,
+    SemVerOperator,
+    StartsWithOperator,
+)
+
+
+class StandardOperators:
+    """The JsonLogic operators available in every evaluation."""
+
+    @classmethod
+    def mapping(cls) -> dict[str, Operator]:
+        return {
+            "var": VarOperator(),
+            "missing": MissingOperator(),
+            "missing_some": MissingSomeOperator(),
+            "if": IfOperator(),
+            "?:": IfOperator(),
+            "and": AndOperator(),
+            "or": OrOperator(),
+            "!": NotOperator(),
+            "!!": ToBoolOperator(),
+            "==": EqualsOperator(),
+            "!=": NotEqualsOperator(),
+            "===": StrictEqualsOperator(),
+            "!==": StrictNotEqualsOperator(),
+            "<": LessThanOperator(),
+            "<=": LessThanOrEqualOperator(),
+            ">": GreaterThanOperator(),
+            ">=": GreaterThanOrEqualOperator(),
+            "+": AddOperator(),
+            "-": SubtractOperator(),
+            "*": MultiplyOperator(),
+            "/": DivideOperator(),
+            "%": ModuloOperator(),
+            "min": MinOperator(),
+            "max": MaxOperator(),
+            "in": InOperator(),
+            "cat": CatOperator(),
+            "substr": SubstrOperator(),
+            "merge": MergeOperator(),
+            "map": MapOperator(),
+            "filter": FilterOperator(),
+            "reduce": ReduceOperator(),
+            "all": AllOperator(),
+            "some": SomeOperator(),
+            "none": NoneMatchOperator(),
+        }
+
+
+class TargetingOperators:
+    """The extension operators used for flag targeting."""
+
+    @classmethod
+    def mapping(cls, hasher: Hasher) -> dict[str, Operator]:
+        return {
+            "starts_with": StartsWithOperator(),
+            "ends_with": EndsWithOperator(),
+            "sem_ver": SemVerOperator(),
+            "fractional": FractionalOperator(hasher),
+        }
+
+
+__all__ = ["StandardOperators", "TargetingOperators"]

fast_feature_engine-0.0.1/src/fast_feature/engine/operators/arithmetic.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from typing import Any
+
+from fast_feature.engine.coercion import Coercion
+from fast_feature.engine.errors import JsonLogicError
+from fast_feature.engine.operator import SimpleOperator
+
+
+class AddOperator(SimpleOperator):
+    def compute(self, *values: Any) -> float:
+        return sum(Coercion.to_number(value) for value in values)
+
+
+class SubtractOperator(SimpleOperator):
+    def compute(self, *values: Any) -> float:
+        if len(values) == 1:
+            return -Coercion.to_number(values[0])
+        return Coercion.to_number(values[0]) - Coercion.to_number(values[1])
+
+
+class MultiplyOperator(SimpleOperator):
+    def compute(self, *values: Any) -> float:
+        product: float = 1
+        for value in values:
+            product *= Coercion.to_number(value)
+        return product
+
+
+class DivideOperator(SimpleOperator):
+    def compute(self, *values: Any) -> float:
+        try:
+            return Coercion.to_number(values[0]) / Coercion.to_number(values[1])
+        except ZeroDivisionError as exc:
+            raise JsonLogicError("division by zero") from exc
+
+
+class ModuloOperator(SimpleOperator):
+    def compute(self, *values: Any) -> float:
+        try:
+            return Coercion.to_number(values[0]) % Coercion.to_number(values[1])
+        except ZeroDivisionError as exc:
+            raise JsonLogicError("modulo by zero") from exc
+
+
+class MinOperator(SimpleOperator):
+    def compute(self, *values: Any) -> float:
+        return min(Coercion.to_number(value) for value in values)
+
+
+class MaxOperator(SimpleOperator):
+    def compute(self, *values: Any) -> float:
+        return max(Coercion.to_number(value) for value in values)

fast_feature_engine-0.0.1/src/fast_feature/engine/operators/collection.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from fast_feature.engine.coercion import Coercion
+from fast_feature.engine.operator import Operator, SimpleOperator
+
+if TYPE_CHECKING:
+    from fast_feature.engine.evaluator import JsonLogicEvaluator
+
+
+class InOperator(SimpleOperator):
+    def compute(self, *values: Any) -> bool:
+        needle, haystack = values[0], values[1]
+        if isinstance(haystack, str):
+            return Coercion.to_str(needle) in haystack
+        if isinstance(haystack, list):
+            return needle in haystack
+        return False
+
+
+class CatOperator(SimpleOperator):
+    def compute(self, *values: Any) -> str:
+        return "".join(Coercion.to_str(value) for value in values)
+
+
+class SubstrOperator(SimpleOperator):
+    def compute(self, *values: Any) -> str:
+        text = Coercion.to_str(values[0])
+        start = int(values[1])
+        if len(values) < 3:
+            return text[start:]
+        length = int(values[2])
+        if length < 0:
+            return text[start:length]
+        return text[start : start + length]
+
+
+class MergeOperator(SimpleOperator):
+    def compute(self, *values: Any) -> list[Any]:
+        merged: list[Any] = []
+        for value in values:
+            if isinstance(value, list):
+                merged.extend(value)
+            else:
+                merged.append(value)
+        return merged
+
+
+class MapOperator(Operator):
+    def apply(self, evaluator: JsonLogicEvaluator, args: list[Any], data: Any) -> list[Any]:
+        collection = evaluator.apply(args[0], data)
+        if not isinstance(collection, list):
+            return []
+        return [evaluator.apply(args[1], item) for item in collection]
+
+
+class FilterOperator(Operator):
+    def apply(self, evaluator: JsonLogicEvaluator, args: list[Any], data: Any) -> list[Any]:
+        collection = evaluator.apply(args[0], data)
+        if not isinstance(collection, list):
+            return []
+        return [item for item in collection if Coercion.is_truthy(evaluator.apply(args[1], item))]
+
+
+class ReduceOperator(Operator):
+    def apply(self, evaluator: JsonLogicEvaluator, args: list[Any], data: Any) -> Any:
+        collection = evaluator.apply(args[0], data)
+        accumulator = evaluator.apply(args[2], data) if len(args) > 2 else None
+        if not isinstance(collection, list):
+            return accumulator
+        for item in collection:
+            accumulator = evaluator.apply(args[1], {"current": item, "accumulator": accumulator})
+        return accumulator
+
+
+class AllOperator(Operator):
+    def apply(self, evaluator: JsonLogicEvaluator, args: list[Any], data: Any) -> bool:
+        collection = evaluator.apply(args[0], data)
+        if not isinstance(collection, list) or not collection:
+            return False
+        return all(Coercion.is_truthy(evaluator.apply(args[1], item)) for item in collection)
+
+
+class SomeOperator(Operator):
+    def apply(self, evaluator: JsonLogicEvaluator, args: list[Any], data: Any) -> bool:
+        collection = evaluator.apply(args[0], data)
+        if not isinstance(collection, list):
+            return False
+        return any(Coercion.is_truthy(evaluator.apply(args[1], item)) for item in collection)
+
+
+class NoneMatchOperator(Operator):
+    def __init__(self) -> None:
+        self._some = SomeOperator()
+
+    def apply(self, evaluator: JsonLogicEvaluator, args: list[Any], data: Any) -> bool:
+        return not self._some.apply(evaluator, args, data)

fast_feature_engine-0.0.1/src/fast_feature/engine/operators/comparison.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from typing import Any
+
+from fast_feature.engine.coercion import Coercion
+from fast_feature.engine.operator import SimpleOperator
+
+
+class EqualsOperator(SimpleOperator):
+    def compute(self, *values: Any) -> bool:
+        return Coercion.soft_equals(values[0], values[1])
+
+
+class NotEqualsOperator(SimpleOperator):
+    def compute(self, *values: Any) -> bool:
+        return not Coercion.soft_equals(values[0], values[1])
+
+
+class StrictEqualsOperator(SimpleOperator):
+    def compute(self, *values: Any) -> bool:
+        return Coercion.hard_equals(values[0], values[1])
+
+
+class StrictNotEqualsOperator(SimpleOperator):
+    def compute(self, *values: Any) -> bool:
+        return not Coercion.hard_equals(values[0], values[1])
+
+
+class LessThanOperator(SimpleOperator):
+    def compute(self, *values: Any) -> bool:
+        if len(values) == 3:
+            return Coercion.less_than(values[0], values[1]) and Coercion.less_than(
+                values[1], values[2]
+            )
+        return Coercion.less_than(values[0], values[1])
+
+
+class LessThanOrEqualOperator(SimpleOperator):
+    def compute(self, *values: Any) -> bool:
+        if len(values) == 3:
+            return Coercion.less_than_or_equal(
+                values[0], values[1]
+            ) and Coercion.less_than_or_equal(values[1], values[2])
+        return Coercion.less_than_or_equal(values[0], values[1])
+
+
+class GreaterThanOperator(SimpleOperator):
+    def compute(self, *values: Any) -> bool:
+        return Coercion.less_than(values[1], values[0])
+
+
+class GreaterThanOrEqualOperator(SimpleOperator):
+    def compute(self, *values: Any) -> bool:
+        return Coercion.less_than_or_equal(values[1], values[0])

fast_feature_engine-0.0.1/src/fast_feature/engine/operators/data.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from fast_feature.engine.operator import Operator
+
+if TYPE_CHECKING:
+    from fast_feature.engine.evaluator import JsonLogicEvaluator
+
+
+class DataPath:
+    """Resolves a dotted variable path against an evaluation data object."""
+
+    _MISSING: Any = object()
+
+    def __init__(self, key: Any) -> None:
+        self._key = key
+
+    def resolve(self, data: Any, default: Any = None) -> Any:
+        found = self._lookup(data)
+        return default if found is self._MISSING else found
+
+    def is_present(self, data: Any) -> bool:
+        return self._lookup(data) not in (self._MISSING, None)
+
+    def _lookup(self, data: Any) -> Any:
+        if self._key is None or self._key == "":
+            return data
+        current = data
+        for part in str(self._key).split("."):
+            if isinstance(current, dict) and part in current:
+                current = current[part]
+            elif isinstance(current, list):
+                try:
+                    current = current[int(part)]
+                except (ValueError, IndexError):
+                    return self._MISSING
+            else:
+                return self._MISSING
+        return current
+
+
+class VarOperator(Operator):
+    def apply(self, evaluator: JsonLogicEvaluator, args: list[Any], data: Any) -> Any:
+        key = evaluator.apply(args[0], data) if args else ""
+        default = evaluator.apply(args[1], data) if len(args) > 1 else None
+        return DataPath(key).resolve(data, default)
+
+
+class MissingOperator(Operator):
+    def apply(self, evaluator: JsonLogicEvaluator, args: list[Any], data: Any) -> list[Any]:
+        keys = [evaluator.apply(arg, data) for arg in args]
+        if len(keys) == 1 and isinstance(keys[0], list):
+            keys = keys[0]
+        return [key for key in keys if not DataPath(key).is_present(data)]
+
+
+class MissingSomeOperator(Operator):
+    def apply(self, evaluator: JsonLogicEvaluator, args: list[Any], data: Any) -> list[Any]:
+        minimum = evaluator.apply(args[0], data)
+        keys = evaluator.apply(args[1], data)
+        if not isinstance(keys, list):
+            return []
+        present = [key for key in keys if DataPath(key).is_present(data)]
+        if len(present) >= int(minimum):
+            return []
+        return [key for key in keys if not DataPath(key).is_present(data)]

fast_feature_engine-0.0.1/src/fast_feature/engine/operators/logic.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from fast_feature.engine.coercion import Coercion
+from fast_feature.engine.operator import Operator, SimpleOperator
+
+if TYPE_CHECKING:
+    from fast_feature.engine.evaluator import JsonLogicEvaluator
+
+
+class IfOperator(Operator):
+    def apply(self, evaluator: JsonLogicEvaluator, args: list[Any], data: Any) -> Any:
+        for index in range(0, len(args) - 1, 2):
+            if Coercion.is_truthy(evaluator.apply(args[index], data)):
+                return evaluator.apply(args[index + 1], data)
+        if len(args) % 2:
+            return evaluator.apply(args[-1], data)
+        return None
+
+
+class AndOperator(Operator):
+    def apply(self, evaluator: JsonLogicEvaluator, args: list[Any], data: Any) -> Any:
+        result: Any = True
+        for arg in args:
+            result = evaluator.apply(arg, data)
+            if not Coercion.is_truthy(result):
+                return result
+        return result
+
+
+class OrOperator(Operator):
+    def apply(self, evaluator: JsonLogicEvaluator, args: list[Any], data: Any) -> Any:
+        result: Any = False
+        for arg in args:
+            result = evaluator.apply(arg, data)
+            if Coercion.is_truthy(result):
+                return result
+        return result
+
+
+class NotOperator(SimpleOperator):
+    def compute(self, *values: Any) -> bool:
+        return not Coercion.is_truthy(values[0])
+
+
+class ToBoolOperator(SimpleOperator):
+    def compute(self, *values: Any) -> bool:
+        return Coercion.is_truthy(values[0])

fast_feature_engine-0.0.1/src/fast_feature/engine/operators/targeting.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from fast_feature.engine.coercion import Coercion
+from fast_feature.engine.hashing import Hasher
+from fast_feature.engine.operator import Operator, SimpleOperator
+from fast_feature.engine.semver import SemanticVersion
+
+if TYPE_CHECKING:
+    from fast_feature.engine.evaluator import JsonLogicEvaluator
+
+
+class StartsWithOperator(SimpleOperator):
+    def compute(self, *values: Any) -> bool:
+        value, prefix = values[0], values[1]
+        if not isinstance(value, str) or not isinstance(prefix, str):
+            return False
+        return value.startswith(prefix)
+
+
+class EndsWithOperator(SimpleOperator):
+    def compute(self, *values: Any) -> bool:
+        value, suffix = values[0], values[1]
+        if not isinstance(value, str) or not isinstance(suffix, str):
+            return False
+        return value.endswith(suffix)
+
+
+class SemVerOperator(SimpleOperator):
+    def compute(self, *values: Any) -> bool:
+        if len(values) != 3:
+            return False
+        left = SemanticVersion.parse(values[0])
+        right = SemanticVersion.parse(values[2])
+        if left is None or right is None:
+            return False
+        return left.satisfies(values[1], right)
+
+
+class FractionalOperator(Operator):
+    """Deterministic percentage rollout, bucketed by a hash of the bucket key."""
+
+    def __init__(self, hasher: Hasher) -> None:
+        self._hasher = hasher
+
+    def apply(self, evaluator: JsonLogicEvaluator, args: list[Any], data: Any) -> Any:
+        if not args:
+            return None
+        first = args[0] if isinstance(args[0], list) else evaluator.apply(args[0], data)
+        if isinstance(first, list):
+            bucket_key = self._default_bucket_key(data)
+            raw_buckets = args
+        else:
+            bucket_key = Coercion.to_str(first)
+            raw_buckets = args[1:]
+
+        names: list[str] = []
+        weights: list[float] = []
+        for bucket in raw_buckets:
+            evaluated = evaluator.apply(bucket, data)
+            if isinstance(evaluated, list) and evaluated:
+                names.append(Coercion.to_str(evaluated[0]))
+                weights.append(float(evaluated[1]) if len(evaluated) > 1 else 1.0)
+
+        total = sum(weights)
+        if not names or total <= 0:
+            return None
+
+        point = self._hasher.hash(bucket_key) / self._hasher.max_value * 100.0
+        cumulative = 0.0
+        for name, weight in zip(names, weights, strict=True):
+            cumulative += weight * 100.0 / total
+            if point < cumulative:
+                return name
+        return names[-1]
+
+    @staticmethod
+    def _default_bucket_key(data: Any) -> str:
+        flag_key = ""
+        targeting_key = ""
+        if isinstance(data, dict):
+            meta = data.get("$flag")
+            if isinstance(meta, dict):
+                flag_key = Coercion.to_str(meta.get("key", ""))
+            targeting_key = Coercion.to_str(data.get("targetingKey", ""))
+        return f"{flag_key}{targeting_key}"

fast_feature_engine-0.0.1/src/fast_feature/engine/registry/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from .registry import OperatorRegistry
+
+__all__ = ["OperatorRegistry"]

fast_feature_engine-0.0.1/src/fast_feature/engine/registry/registry.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from fast_feature.engine.operator import Operator
+
+
+class OperatorRegistry:
+    """A name-to-operator lookup used by the evaluator."""
+
+    def __init__(self, operators: dict[str, Operator] | None = None) -> None:
+        self._operators: dict[str, Operator] = dict(operators or {})
+
+    def register(self, name: str, operator: Operator) -> None:
+        self._operators[name] = operator
+
+    def resolve(self, name: str) -> Operator | None:
+        return self._operators.get(name)
+
+    def extended_with(self, operators: dict[str, Operator]) -> OperatorRegistry:
+        """Return a new registry with ``operators`` added on top of this one."""
+        merged = dict(self._operators)
+        merged.update(operators)
+        return OperatorRegistry(merged)
+
+    def __contains__(self, name: object) -> bool:
+        return name in self._operators

fast_feature_engine-0.0.1/src/fast_feature/engine/semver/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from .semantic_version import SemanticVersion
+
+__all__ = ["SemanticVersion"]

fast_feature_engine-0.0.1/src/fast_feature/engine/semver/semantic_version.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Any, ClassVar
+
+
+@dataclass(frozen=True, order=True)
+class SemanticVersion:
+    """A comparable ``major.minor.patch`` version."""
+
+    major: int
+    minor: int
+    patch: int
+
+    _PATTERN: ClassVar[re.Pattern[str]] = re.compile(r"^v?(\d+)(?:\.(\d+))?(?:\.(\d+))?")
+
+    @classmethod
+    def parse(cls, value: Any) -> SemanticVersion | None:
+        if not isinstance(value, str):
+            return None
+        match = cls._PATTERN.match(value.strip())
+        if match is None:
+            return None
+        return cls(int(match.group(1)), int(match.group(2) or 0), int(match.group(3) or 0))
+
+    def satisfies(self, operator: Any, other: SemanticVersion) -> bool:
+        if operator in ("=", "=="):
+            return self == other
+        if operator == "!=":
+            return self != other
+        if operator == "<":
+            return self < other
+        if operator == "<=":
+            return self <= other
+        if operator == ">":
+            return self > other
+        if operator == ">=":
+            return self >= other
+        if operator == "^":
+            return self.major == other.major
+        if operator == "~":
+            return self.major == other.major and self.minor == other.minor
+        return False