krons 0.1.0__py3-none-any.whl

kronos/enforcement/rule.py

@@ -0,0 +1,312 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from abc import abstractmethod
+from dataclasses import dataclass, field
+from enum import IntEnum, auto
+from typing import Any
+
+from kronos.errors import ValidationError
+from kronos.types import Params
+
+__all__ = ("Rule", "RuleParams", "RuleQualifier", "ValidationError")
+
+
+class RuleQualifier(IntEnum):
+    """Qualifier types for rules - determines WHEN a rule applies.
+
+    - FIELD: Match by field name (e.g., "confidence", "output")
+    - ANNOTATION: Match by type annotation (e.g., str, int, float)
+    - CONDITION: Match by custom condition (e.g., is BaseModel subclass)
+
+    Default precedence order: FIELD > ANNOTATION > CONDITION
+    """
+
+    FIELD = auto()
+    ANNOTATION = auto()
+    CONDITION = auto()
+
+    @classmethod
+    def from_str(cls, s: str) -> RuleQualifier:
+        """Convert string to RuleQualifier."""
+        s = s.strip().upper()
+        if s == "FIELD":
+            return cls.FIELD
+        elif s == "ANNOTATION":
+            return cls.ANNOTATION
+        elif s == "CONDITION":
+            return cls.CONDITION
+        else:
+            raise ValueError(f"Unknown RuleQualifier: {s}")
+
+
+def _decide_qualifier_order(
+    qualifier: str | RuleQualifier | None = None,
+) -> list[RuleQualifier]:
+    """Determine qualifier precedence order (default: FIELD > ANNOTATION > CONDITION).
+
+    Args:
+        qualifier: Preferred qualifier moved to front of order. None uses default.
+
+    Returns:
+        List of RuleQualifier in precedence order.
+    """
+    default_order = [
+        RuleQualifier.FIELD,
+        RuleQualifier.ANNOTATION,
+        RuleQualifier.CONDITION,
+    ]
+
+    if qualifier is None:
+        return default_order
+
+    if isinstance(qualifier, str):
+        qualifier = RuleQualifier.from_str(qualifier)
+
+    default_order.remove(qualifier)
+    return [qualifier, *default_order]
+
+
+@dataclass(slots=True, frozen=True)
+class RuleParams(Params):
+    """Immutable configuration for rules.
+
+    Defines:
+    - WHAT the rule applies to (types or fields)
+    - HOW to determine applicability (default_qualifier)
+    - WHETHER to auto-fix (auto_fix)
+    - ADDITIONAL validation parameters (kw)
+
+    Uses kron.types.Params (leaner than Pydantic BaseModel).
+    """
+
+    apply_types: set[type] = field(default_factory=set)
+    """Types this rule applies to (e.g., {str, int})"""
+
+    apply_fields: set[str] = field(default_factory=set)
+    """Field names this rule applies to (e.g., {"confidence", "output"})"""
+
+    default_qualifier: RuleQualifier = RuleQualifier.FIELD
+    """Preferred qualifier type"""
+
+    auto_fix: bool = False
+    """Enable automatic fixing on validation failure"""
+
+    kw: dict = field(default_factory=dict)
+    """Additional validation parameters"""
+
+    def __post_init__(self) -> None:
+        """Validate after dataclass initialization."""
+        self._validate()
+
+    def _validate(self) -> None:
+        """Validate params consistency (extensible hook for subclasses).
+
+        Rules use multiple qualifier mechanisms (OR matching):
+        - apply_types: ANNOTATION qualifier (type-based)
+        - apply_fields: FIELD qualifier (name-based)
+        - rule_condition(): CONDITION qualifier (custom logic)
+
+        Empty sets are valid for explicit/manual rule invocation.
+        """
+        pass
+
+
+class Rule:
+    """Base validation rule with auto-correction support.
+
+    Pattern from lionagi v0.2.2 + lionherd-old:
+    1. apply() - Does this rule apply? (uses qualifiers)
+    2. validate() - Is the value valid? (abstract, subclass implements)
+    3. perform_fix() - Can we auto-correct? (optional, if auto_fix=True)
+
+    Usage:
+        # Create rule
+        rule = StringRule(min_length=1, max_length=100)
+
+        # Check if applies
+        if await rule.apply("name", "Ocean", str):
+            # Validate + fix
+            result = await rule.invoke("name", "Ocean", str)
+    """
+
+    def __init__(self, params: RuleParams, **kw):
+        """Initialize rule with parameters.
+
+        Args:
+            params: Rule configuration
+            **kw: Additional validation kwargs (merged with params.kw)
+        """
+        if kw:
+            # Merge additional kwargs using with_updates
+            params = params.with_updates(kw={**params.kw, **kw})
+        self.params = params
+
+    @property
+    def apply_types(self) -> set[type]:
+        """Types this rule applies to (ANNOTATION qualifier)."""
+        return self.params.apply_types
+
+    @property
+    def apply_fields(self) -> set[str]:
+        """Field names this rule applies to (FIELD qualifier)."""
+        return self.params.apply_fields
+
+    @property
+    def default_qualifier(self) -> RuleQualifier:
+        """Preferred qualifier type for apply() precedence."""
+        return self.params.default_qualifier
+
+    @property
+    def auto_fix(self) -> bool:
+        """Whether perform_fix() is called on validation failure."""
+        return self.params.auto_fix
+
+    @property
+    def validation_kwargs(self) -> dict:
+        """Additional parameters passed to validate()."""
+        return self.params.kw
+
+    async def rule_condition(self, k: str, v: Any, t: type, **kw) -> bool:
+        """Custom condition for CONDITION qualifier.
+
+        Override in subclass to use CONDITION qualifier.
+
+        Args:
+            k: Field name
+            v: Field value
+            t: Field type
+            **kw: Additional kwargs
+
+        Returns:
+            True if rule should apply
+        """
+        raise NotImplementedError(
+            f"{self.__class__.__name__} must implement rule_condition() to use CONDITION qualifier"
+        )
+
+    async def _apply(self, k: str, v: Any, t: type, q: RuleQualifier, **kw) -> bool:
+        """Determine if rule applies based on qualifier.
+
+        Args:
+            k: Field name
+            v: Field value
+            t: Field type
+            q: Qualifier type
+            **kw: Additional kwargs
+
+        Returns:
+            True if rule applies
+        """
+        match q:
+            case RuleQualifier.FIELD:
+                return k in self.apply_fields
+
+            case RuleQualifier.ANNOTATION:
+                return t in self.apply_types
+
+            case RuleQualifier.CONDITION:
+                return await self.rule_condition(k, v, t, **kw)
+
+    async def apply(
+        self,
+        k: str,
+        v: Any,
+        t: type | None = None,
+        qualifier: str | RuleQualifier | None = None,
+        **kw,
+    ) -> bool:
+        """Check if rule applies using qualifier precedence.
+
+        Args:
+            k: Field name
+            v: Field value
+            t: Field type (optional)
+            qualifier: Override default qualifier order
+            **kw: Additional kwargs for condition checking
+
+        Returns:
+            True if rule applies (any qualifier matches)
+        """
+        _order = _decide_qualifier_order(qualifier)
+
+        for q in _order:
+            try:
+                if await self._apply(k, v, t or type(v), q, **kw):
+                    return True
+            except NotImplementedError:
+                continue
+
+        return False
+
+    @abstractmethod
+    async def validate(self, v: Any, t: type, **kw) -> None:
+        """Validate value (abstract, implement in subclass).
+
+        Args:
+            v: Value to validate
+            t: Expected type
+            **kw: Additional validation parameters
+
+        Raises:
+            Exception: If validation fails
+        """
+        pass
+
+    async def perform_fix(self, v: Any, t: type) -> Any:
+        """Attempt to fix invalid value (optional, override in subclass).
+
+        Args:
+            v: Value to fix
+            t: Expected type
+
+        Returns:
+            Fixed value
+
+        Raises:
+            NotImplementedError: If auto_fix=True but perform_fix not implemented
+        """
+        raise NotImplementedError(
+            f"{self.__class__.__name__} must implement perform_fix() to use auto_fix=True"
+        )
+
+    async def invoke(
+        self, k: str, v: Any, t: type | None = None, *, auto_fix: bool | None = None
+    ) -> Any:
+        """Execute validation with optional auto-fixing.
+
+        Args:
+            k: Field name (for error messages)
+            v: Value to validate
+            t: Field type (optional)
+            auto_fix: Override self.auto_fix for this invocation (thread-safe)
+
+        Returns:
+            Validated (and possibly fixed) value
+
+        Raises:
+            ValidationError: If validation fails and auto_fix disabled
+        """
+        effective_type = t or type(v)
+        should_auto_fix = auto_fix if auto_fix is not None else self.auto_fix
+        try:
+            await self.validate(v, effective_type, **self.validation_kwargs)
+            return v
+        except Exception as e:
+            if should_auto_fix:
+                try:
+                    return await self.perform_fix(v, effective_type)
+                except Exception as e1:
+                    raise ValidationError(f"Failed to fix field '{k}': {e1}") from e
+            raise ValidationError(f"Failed to validate field '{k}': {e}") from e
+
+    def __repr__(self) -> str:
+        """String representation."""
+        return (
+            f"{self.__class__.__name__}("
+            f"types={self.apply_types}, "
+            f"fields={self.apply_fields}, "
+            f"auto_fix={self.auto_fix})"
+        )

kronos/enforcement/service.py

@@ -0,0 +1,370 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+"""KronService - typed action handlers with policy evaluation."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Any
+
+from pydantic import Field, PrivateAttr
+
+from kronos.services import ServiceBackend, ServiceConfig
+
+from .context import RequestContext
+from .policy import EnforcementLevel, PolicyEngine, PolicyResolver
+
+logger = logging.getLogger(__name__)
+
+__all__ = (
+    "ActionMeta",
+    "KronConfig",
+    "KronService",
+    "action",
+    "get_action_meta",
+)
+
+
+class KronConfig(ServiceConfig):
+    """Configuration for KronService.
+
+    Attributes:
+        operable: Canonical Operable containing all field specs for this service.
+        action_timeout: Timeout for action execution (None = no timeout).
+        use_policies: Enable policy evaluation.
+        policy_timeout: Timeout for policy evaluation.
+        fail_open_on_engine_error: Allow action if engine fails (DANGEROUS).
+        hooks: Available hooks {name: callable}.
+    """
+
+    operable: Any = None
+    """Canonical Operable for the service's field namespace."""
+
+    action_timeout: float | None = None
+    """Timeout for action execution in seconds. None means no timeout."""
+
+    use_policies: bool = True
+    """Enable policy evaluation."""
+
+    policy_timeout: float = 10.0
+    """Timeout for policy evaluation in seconds."""
+
+    fail_open_on_engine_error: bool = False
+    """If True, allow action when engine fails. DANGEROUS for production."""
+
+    hooks: dict[str, Callable[..., Awaitable[Any]]] = Field(default_factory=dict)
+    """Available hooks {name: hook_function}."""
+
+
+_ACTION_ATTR = "_kron_action"
+
+
+@dataclass(frozen=True, slots=True)
+class ActionMeta:
+    """Metadata for an action handler.
+
+    Attributes:
+        name: Action identifier (e.g., "consent.grant").
+        inputs: Field names from service operable used as inputs.
+        outputs: Field names from service operable used as outputs.
+        pre_hooks: Hook names to run before action.
+        post_hooks: Hook names to run after action.
+    """
+
+    name: str
+    inputs: frozenset[str] = frozenset()
+    outputs: frozenset[str] = frozenset()
+    pre_hooks: tuple[str, ...] = ()
+    post_hooks: tuple[str, ...] = ()
+
+    # Lazily computed types (set by service at registration)
+    _options_type: Any = None
+    _result_type: Any = None
+
+
+def action(
+    name: str,
+    inputs: set[str] | None = None,
+    outputs: set[str] | None = None,
+    pre_hooks: list[str] | None = None,
+    post_hooks: list[str] | None = None,
+) -> Callable[[Callable], Callable]:
+    """Decorator to declare action handler metadata.
+
+    Args:
+        name: Action identifier (e.g., "consent.grant").
+        inputs: Field names from service operable used as inputs.
+        outputs: Field names from service operable used as outputs.
+        pre_hooks: Hook names to run before action.
+        post_hooks: Hook names to run after action.
+
+    Usage:
+        @action(
+            name="consent.grant",
+            inputs={"permissions", "subject_id"},
+            outputs={"consent_id", "granted_at"},
+        )
+        async def _handle_grant(self, options, ctx):
+            ...
+    """
+
+    def decorator(func: Callable) -> Callable:
+        meta = ActionMeta(
+            name=name,
+            inputs=frozenset(inputs or set()),
+            outputs=frozenset(outputs or set()),
+            pre_hooks=tuple(pre_hooks or []),
+            post_hooks=tuple(post_hooks or []),
+        )
+        setattr(func, _ACTION_ATTR, meta)
+        return func
+
+    return decorator
+
+
+def get_action_meta(handler: Callable) -> ActionMeta | None:
+    """Get action metadata from a handler method."""
+    return getattr(handler, _ACTION_ATTR, None)
+
+
+# =============================================================================
+# KronService
+# =============================================================================
+
+
+class KronService(ServiceBackend):
+    """Service backend with typed actions.
+
+    Subclasses implement action handlers with @action decorator.
+    Actions derive typed I/O from service's canonical operable.
+
+    Example:
+        class ConsentService(KronService):
+            config = KronConfig(
+                name="consent",
+                operable=Operable([
+                    Spec("permissions", list[str]),
+                    Spec("consent_id", UUID),
+                    Spec("granted_at", datetime),
+                    Spec("subject_id", FK[Subject]),
+                ]),
+            )
+
+            @action(
+                name="consent.grant",
+                inputs={"permissions", "subject_id"},
+                outputs={"consent_id", "granted_at"},
+            )
+            async def _handle_grant(self, options, ctx):
+                ...
+
+        service = ConsentService()
+        result = await service.call("consent.grant", options, ctx)
+    """
+
+    config: KronConfig = Field(default_factory=KronConfig)
+    _policy_engine: PolicyEngine | None = PrivateAttr(default=None)
+    _policy_resolver: PolicyResolver | None = PrivateAttr(default=None)
+    _action_registry: dict[str, tuple[Callable, ActionMeta]] = PrivateAttr(default_factory=dict)
+
+    def __init__(
+        self,
+        config: KronConfig | None = None,
+        policy_engine: PolicyEngine | None = None,
+        policy_resolver: PolicyResolver | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """Initialize service with optional policy engine and resolver.
+
+        Args:
+            config: Service configuration.
+            policy_engine: PolicyEngine for policy evaluation.
+            policy_resolver: PolicyResolver for determining applicable policies.
+        """
+        super().__init__(config=config, **kwargs)
+        self._policy_engine = policy_engine
+        self._policy_resolver = policy_resolver
+        self._action_registry = {}
+        self._register_actions()
+
+    def _register_actions(self) -> None:
+        """Scan for @action decorated methods and register them."""
+        for name in dir(self):
+            if name.startswith("_"):
+                method = getattr(self, name, None)
+                if method and callable(method):
+                    meta = get_action_meta(method)
+                    if meta:
+                        self._action_registry[meta.name] = (method, meta)
+                        self._build_action_types(meta)
+
+    def _build_action_types(self, meta: ActionMeta) -> None:
+        """Build options_type and result_type for an action from service operable."""
+        if not self.config.operable:
+            return
+
+        operable = self.config.operable
+
+        # Validate inputs/outputs exist in operable
+        allowed = operable.allowed()
+        invalid_inputs = meta.inputs - allowed
+        invalid_outputs = meta.outputs - allowed
+
+        if invalid_inputs:
+            logger.warning(
+                "Action '%s' has inputs not in operable: %s",
+                meta.name,
+                invalid_inputs,
+            )
+        if invalid_outputs:
+            logger.warning(
+                "Action '%s' has outputs not in operable: %s",
+                meta.name,
+                invalid_outputs,
+            )
+
+        # Build typed structures (frozen dataclasses)
+        if meta.inputs:
+            options_type = operable.compose_structure(
+                _to_pascal(meta.name) + "Options",
+                include=set(meta.inputs),
+                frozen=True,
+            )
+            object.__setattr__(meta, "_options_type", options_type)
+
+        if meta.outputs:
+            result_type = operable.compose_structure(
+                _to_pascal(meta.name) + "Result",
+                include=set(meta.outputs),
+                frozen=True,
+            )
+            object.__setattr__(meta, "_result_type", result_type)
+
+    @property
+    def has_engine(self) -> bool:
+        """True if policy engine is configured."""
+        return self._policy_engine is not None
+
+    @property
+    def has_resolver(self) -> bool:
+        """True if policy resolver is configured."""
+        return self._policy_resolver is not None
+
+    async def call(
+        self,
+        name: str,
+        options: Any,
+        ctx: RequestContext,
+    ) -> Any:
+        """Call an action by name.
+
+        Args:
+            name: Action name (e.g., "consent.grant").
+            options: Input data (dict or typed dataclass).
+            ctx: Request context.
+
+        Returns:
+            Action result.
+
+        Raises:
+            ValueError: If action not found.
+            PermissionError: If policy blocks action.
+        """
+        handler, meta = self._fetch_handler(name)
+
+        # Update context
+        ctx.name = name
+
+        # Run pre-hooks
+        await self._run_hooks(meta.pre_hooks, options, ctx)
+
+        # Evaluate policies
+        if self.config.use_policies and self._policy_engine:
+            await self._evaluate_policies(ctx)
+
+        # Validate options if we have typed options_type
+        if meta._options_type and self.config.operable:
+            options = self.config.operable.validate_instance(meta._options_type, options)
+
+        # Execute handler
+        result = await handler(options, ctx)
+
+        # Run post-hooks
+        await self._run_hooks(meta.post_hooks, options, ctx, result=result)
+
+        return result
+
+    def _fetch_handler(self, name: str) -> tuple[Callable, ActionMeta]:
+        """Fetch handler and metadata by action name.
+
+        Args:
+            name: Action name.
+
+        Returns:
+            Tuple of (handler, ActionMeta).
+
+        Raises:
+            ValueError: If action not found.
+        """
+        if name not in self._action_registry:
+            raise ValueError(f"Unknown action: {name}")
+        return self._action_registry[name]
+
+    async def _run_hooks(
+        self,
+        hook_names: tuple[str, ...],
+        options: Any,
+        ctx: RequestContext,
+        result: Any = None,
+    ) -> None:
+        """Run named hooks from config.hooks."""
+        for hook_name in hook_names:
+            hook_fn = self.config.hooks.get(hook_name)
+            if hook_fn:
+                try:
+                    await hook_fn(self, options, ctx, result)
+                except Exception as e:
+                    logger.error("Hook '%s' failed: %s", hook_name, e)
+            else:
+                logger.warning("Hook '%s' not found in config.hooks", hook_name)
+
+    async def _evaluate_policies(self, ctx: RequestContext) -> None:
+        """Evaluate policies via engine."""
+        if not self._policy_engine or not self._policy_resolver:
+            return
+
+        try:
+            resolved = self._policy_resolver.resolve(ctx)
+
+            if not resolved:
+                return
+
+            policy_ids = [p.policy_id for p in resolved]
+            input_data = ctx.to_dict()
+
+            results = await self._policy_engine.evaluate_batch(policy_ids, input_data)
+
+            for result in results:
+                if EnforcementLevel.is_blocking(result):
+                    raise PermissionError(f"Policy {result.policy_id} blocked: {result.message}")
+
+        except PermissionError:
+            raise
+        except Exception as e:
+            logger.error("Policy evaluation failed: %s", e)
+            if not self.config.fail_open_on_engine_error:
+                raise PermissionError(f"Policy engine error: {e}")
+
+
+def _to_pascal(name: str) -> str:
+    """Convert action name to PascalCase.
+
+    consent.grant -> ConsentGrant
+    consent_grant -> ConsentGrant
+    """
+    # Replace dots and underscores, capitalize each part
+    parts = name.replace(".", "_").split("_")
+    return "".join(part.capitalize() for part in parts)