krons 0.1.0__py3-none-any.whl

kronos/enforcement/validator.py

@@ -0,0 +1,198 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from collections import deque
+from datetime import datetime
+from typing import TYPE_CHECKING, Any, ClassVar
+
+from kronos.types import is_sentinel
+from kronos.utils.concurrency import is_coro_func
+
+from .registry import RuleRegistry, get_default_registry
+from .rule import Rule, ValidationError
+
+if TYPE_CHECKING:
+    from kronos.specs import Operable, Spec
+
+__all__ = ("Validator",)
+
+
+class Validator:
+    DEFAULT_MAX_LOG_ENTRIES: ClassVar[int] = 1000
+
+    def __init__(
+        self,
+        registry: RuleRegistry | None = None,
+        max_log_entries: int | None = None,
+    ):
+        self.registry = registry or get_default_registry()
+        max_entries = (
+            max_log_entries if max_log_entries is not None else self.DEFAULT_MAX_LOG_ENTRIES
+        )
+        self.validation_log: deque[dict[str, Any]] = deque(
+            maxlen=max_entries if max_entries > 0 else None
+        )
+
+    def log_validation_error(self, field: str, value: Any, error: str) -> None:
+        """Log a validation error with timestamp.
+
+        Args:
+            field: Field name that failed validation
+            value: Value that failed validation
+            error: Error message
+        """
+        log_entry = {
+            "field": field,
+            "value": value,
+            "error": error,
+            "timestamp": datetime.now().isoformat(),
+        }
+        self.validation_log.append(log_entry)
+
+    def get_validation_summary(self) -> dict[str, Any]:
+        """Get summary of validation log.
+
+        Returns:
+            Dict with total_errors, fields_with_errors, and error_entries
+        """
+        fields_with_errors = set()
+        for entry in self.validation_log:
+            if "field" in entry:
+                fields_with_errors.add(entry["field"])
+
+        return {
+            "total_errors": len(self.validation_log),
+            "fields_with_errors": sorted(list(fields_with_errors)),
+            "error_entries": list(self.validation_log),
+        }
+
+    def clear_log(self) -> None:
+        """Clear the validation log."""
+        self.validation_log.clear()
+
+    def get_rule_for_spec(self, spec: Spec) -> Rule | None:
+        override = spec.get("rule")
+        if override is not None and isinstance(override, Rule):
+            return override
+
+        return self.registry.get_rule(
+            base_type=spec.base_type,
+            field_name=spec.name if spec.name else None,
+        )
+
+    async def validate_spec(
+        self,
+        spec: Spec,
+        value: Any,
+        auto_fix: bool = True,
+        strict: bool = True,
+    ) -> Any:
+        field_name = spec.name or "<unnamed>"
+
+        if value is None:
+            if spec.is_nullable:
+                return None
+            try:
+                value = await spec.acreate_default_value()
+            except ValueError:
+                if strict:
+                    error_msg = f"Field '{field_name}' is None but not nullable and has no default"
+                    self.log_validation_error(field_name, value, error_msg)
+                    raise ValidationError(error_msg)
+                return value
+
+        rule = self.get_rule_for_spec(spec)
+
+        if spec.is_listable:
+            if not isinstance(value, list):
+                if auto_fix:
+                    value = [value]
+                else:
+                    error_msg = f"Field '{field_name}' expected list, got {type(value).__name__}"
+                    self.log_validation_error(field_name, value, error_msg)
+                    raise ValidationError(error_msg)
+
+            validated_items = []
+            for i, item in enumerate(value):
+                item_name = f"{field_name}[{i}]"
+                if rule is not None:
+                    try:
+                        validated_item = await rule.invoke(
+                            item_name, item, spec.base_type, auto_fix=auto_fix
+                        )
+                    except Exception as e:
+                        self.log_validation_error(item_name, item, str(e))
+                        raise
+                else:
+                    validated_item = item
+                validated_items.append(validated_item)
+
+            value = validated_items
+        else:
+            if rule is None:
+                if strict:
+                    error_msg = (
+                        f"No rule found for field '{field_name}' with type {spec.base_type}. "
+                        f"Register a rule or set strict=False."
+                    )
+                    self.log_validation_error(field_name, value, error_msg)
+                    raise ValidationError(error_msg)
+            else:
+                try:
+                    value = await rule.invoke(field_name, value, spec.base_type, auto_fix=auto_fix)
+                except Exception as e:
+                    self.log_validation_error(field_name, value, str(e))
+                    raise
+
+        custom_validators = spec.get("validator")
+        if is_sentinel(custom_validators) or custom_validators is None:
+            validators = []
+        elif callable(custom_validators):
+            validators = [custom_validators]
+        elif isinstance(custom_validators, list):
+            validators = custom_validators
+        else:
+            validators = []
+
+        for validator_fn in validators:
+            if not callable(validator_fn):
+                continue
+            try:
+                if is_coro_func(validator_fn):
+                    value = await validator_fn(value)
+                else:
+                    value = validator_fn(value)
+            except Exception as e:
+                error_msg = f"Custom validator failed for '{field_name}': {e}"
+                self.log_validation_error(field_name, value, error_msg)
+                raise ValidationError(error_msg) from e
+
+        return value
+
+    async def validate_operable(
+        self,
+        data: dict[str, Any],
+        operable: Operable,
+        capabilities: set[str] | None = None,
+        auto_fix: bool = True,
+        strict: bool = True,
+    ) -> dict[str, Any]:
+        capabilities = capabilities or operable.allowed()
+        validated: dict[str, Any] = {}
+
+        for spec in operable.get_specs():
+            field_name = spec.name
+            if is_sentinel(field_name) or not isinstance(field_name, str):
+                continue
+
+            if field_name not in capabilities:
+                continue
+
+            value = data.get(field_name)
+            validated[field_name] = await self.validate_spec(
+                spec, value, auto_fix=auto_fix, strict=strict
+            )
+
+        return validated

kronos/errors.py

@@ -0,0 +1,146 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+"""Kron exception hierarchy with structured details and retryability.
+
+All exceptions inherit from KronError and include:
+    - message: Human-readable description
+    - details: Structured context dict
+    - retryable: Whether retry might succeed
+
+Naming: KronConnectionError/KronTimeoutError avoid shadowing builtins.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .protocols import Serializable, implements
+
+__all__ = (
+    "AccessError",
+    "ConfigurationError",
+    "ExecutionError",
+    "ExistsError",
+    "KronConnectionError",
+    "KronError",
+    "KronTimeoutError",
+    "NotFoundError",
+    "OperationError",
+    "QueueFullError",
+    "ValidationError",
+)
+
+
+@implements(Serializable)
+class KronError(Exception):
+    """Base exception for kron. Serializable with structured details.
+
+    Subclasses set default_message and default_retryable.
+    Use cause= to chain exceptions with preserved traceback.
+
+    Attributes:
+        message: Human-readable description.
+        details: Structured context for debugging/logging.
+        retryable: Whether retry might succeed.
+    """
+
+    default_message: str = "kron error"
+    default_retryable: bool = True
+
+    def __init__(
+        self,
+        message: str | None = None,
+        *,
+        details: dict[str, Any] | None = None,
+        retryable: bool | None = None,
+        cause: Exception | None = None,
+    ):
+        """Initialize with optional message, details, retryability, and cause."""
+        self.message = message or self.default_message
+        self.details = details or {}
+        self.retryable = retryable if retryable is not None else self.default_retryable
+
+        if cause:
+            self.__cause__ = cause  # Preserve traceback
+
+        super().__init__(self.message)
+
+    def to_dict(self, **kwargs: Any) -> dict[str, Any]:
+        """Serialize to dict: {error, message, retryable, details?}."""
+        return {
+            "error": self.__class__.__name__,
+            "message": self.message,
+            "retryable": self.retryable,
+            **({"details": self.details} if self.details else {}),
+        }
+
+
+class ValidationError(KronError):
+    """Data validation failure. Raise when input fails schema/constraint checks."""
+
+    default_message = "Validation failed"
+    default_retryable = False
+
+
+class AccessError(KronError):
+    """Permission denied. Raise when capability/resource access is blocked."""
+
+    default_message = "Access denied"
+    default_retryable = False
+
+
+class ConfigurationError(KronError):
+    """Invalid configuration. Raise when setup/config is incorrect."""
+
+    default_message = "Configuration error"
+    default_retryable = False
+
+
+class ExecutionError(KronError):
+    """Execution failure. Raise when Event/Calling invoke fails (often transient)."""
+
+    default_message = "Execution failed"
+    default_retryable = True
+
+
+class KronConnectionError(KronError):
+    """Network/connection failure. Named to avoid shadowing builtins."""
+
+    default_message = "Connection error"
+    default_retryable = True
+
+
+class KronTimeoutError(KronError):
+    """Operation timeout. Named to avoid shadowing builtins."""
+
+    default_message = "Operation timed out"
+    default_retryable = True
+
+
+class NotFoundError(KronError):
+    """Resource/item not found. Raise when lookup fails."""
+
+    default_message = "Item not found"
+    default_retryable = False
+
+
+class ExistsError(KronError):
+    """Duplicate item. Raise when creating item that already exists."""
+
+    default_message = "Item already exists"
+    default_retryable = False
+
+
+class QueueFullError(KronError):
+    """Capacity exceeded. Raise when queue/buffer is full."""
+
+    default_message = "Queue is full"
+    default_retryable = True
+
+
+class OperationError(KronError):
+    """Generic operation failure. Use for unclassified operation errors."""
+
+    default_message = "Operation failed"
+    default_retryable = False

kronos/operations/__init__.py

@@ -0,0 +1,32 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+"""Operations: executable graph nodes with dependency-aware execution.
+
+Core types:
+    Operation: Node + Event hybrid for graph-based execution.
+    OperationRegistry: Per-session factory mapping.
+    OperationGraphBuilder (Builder): Fluent DAG construction.
+
+Execution:
+    flow(): Execute DAG, return results dict.
+    flow_stream(): Execute DAG, yield results incrementally.
+"""
+
+from __future__ import annotations
+
+from .builder import Builder, OperationGraphBuilder
+from .flow import DependencyAwareExecutor, flow, flow_stream
+from .node import Operation, create_operation
+from .registry import OperationRegistry
+
+__all__ = (
+    "Builder",
+    "DependencyAwareExecutor",
+    "Operation",
+    "OperationGraphBuilder",
+    "OperationRegistry",
+    "create_operation",
+    "flow",
+    "flow_stream",
+)

kronos/operations/builder.py

@@ -0,0 +1,228 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+"""Fluent builder for operation DAGs.
+
+Build graphs with chained .add() calls, automatic sequential linking,
+and explicit dependency management. Alias: Builder = OperationGraphBuilder.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+from uuid import UUID
+
+from kronos.core import Edge, Graph
+from kronos.types import Undefined, UndefinedType, is_sentinel, not_sentinel
+from kronos.utils._utils import to_uuid
+
+from .node import Operation
+
+if TYPE_CHECKING:
+    from kronos.session import Branch
+
+__all__ = ("Builder", "OperationGraphBuilder")
+
+
+def _resolve_branch_ref(branch: Any) -> UUID | str:
+    """Convert branch reference to UUID or trimmed name string.
+
+    Raises:
+        ValueError: If branch is not a valid UUID, Branch, or non-empty string.
+    """
+    try:
+        return to_uuid(branch)
+    except (ValueError, TypeError):
+        pass
+
+    if isinstance(branch, str) and branch.strip():
+        return branch.strip()
+
+    raise ValueError(f"Invalid branch reference: {branch}")
+
+
+class OperationGraphBuilder:
+    """Fluent builder for operation DAGs with automatic linking.
+
+    Operations added sequentially auto-link unless depends_on is specified.
+    Use depends_on=[] for independent operations, depends_on=["op1"] for explicit.
+
+    Example:
+        graph = (Builder()
+            .add("fetch", "http_get", {"url": "..."})
+            .add("parse", "json_parse")  # auto-links to fetch
+            .add("validate", "schema_check", depends_on=["parse"])
+            .build())
+
+    Attributes:
+        graph: Underlying Graph being built.
+    """
+
+    def __init__(self, graph: Graph | UndefinedType = Undefined):
+        """Initialize builder, optionally with existing graph.
+
+        Args:
+            graph: Pre-existing Graph to extend, or Undefined for new.
+        """
+        self.graph = Graph() if is_sentinel(graph) else graph
+        self._nodes: dict[str, Operation] = {}
+        self._executed: set[UUID] = set()
+        self._current_heads: list[str] = []
+
+    def add(
+        self,
+        name: str,
+        operation: str,
+        parameters: dict[str, Any] | Any | UndefinedType = Undefined,
+        depends_on: list[str] | UndefinedType = Undefined,
+        branch: str | UUID | Branch | UndefinedType = Undefined,
+        inherit_context: bool = False,
+        metadata: dict[str, Any] | UndefinedType = Undefined,
+    ) -> OperationGraphBuilder:
+        """Add operation to graph.
+
+        Args:
+            name: Unique operation name for reference.
+            operation: Operation type (registry key).
+            parameters: Factory arguments (dict or model).
+            depends_on: Explicit dependencies. Undefined=auto-link, []=independent.
+            branch: Target branch (Branch|UUID|str). Undefined=default.
+            inherit_context: Store primary_dependency for context inheritance.
+            metadata: Additional metadata dict.
+
+        Returns:
+            Self for chaining.
+
+        Raises:
+            ValueError: If name exists or dependency not found.
+        """
+        if name in self._nodes:
+            raise ValueError(f"Operation with name '{name}' already exists")
+
+        resolved_params = {} if is_sentinel(parameters) else parameters
+        resolved_metadata = {} if is_sentinel(metadata) else metadata
+        op = Operation(
+            operation_type=operation,
+            parameters=resolved_params,
+            metadata=resolved_metadata,
+            streaming=False,
+        )
+        op.metadata["name"] = name
+
+        if not_sentinel(branch):
+            op.metadata["branch"] = _resolve_branch_ref(branch)
+
+        if inherit_context and not_sentinel(depends_on) and depends_on:
+            op.metadata["inherit_context"] = True
+            op.metadata["primary_dependency"] = self._nodes[depends_on[0]].id
+
+        self.graph.add_node(op)
+        self._nodes[name] = op
+
+        if not_sentinel(depends_on):
+            for dep_name in depends_on:
+                if dep_name not in self._nodes:
+                    raise ValueError(f"Dependency '{dep_name}' not found")
+                dep_node = self._nodes[dep_name]
+                edge = Edge(head=dep_node.id, tail=op.id, label=["depends_on"])
+                self.graph.add_edge(edge)
+        elif self._current_heads:
+            for head_name in self._current_heads:
+                if head_name in self._nodes:
+                    head_node = self._nodes[head_name]
+                    edge = Edge(head=head_node.id, tail=op.id, label=["sequential"])
+                    self.graph.add_edge(edge)
+
+        self._current_heads = [name]
+        return self
+
+    def depends_on(
+        self,
+        target: str,
+        *dependencies: str,
+        label: list[str] | UndefinedType = Undefined,
+    ) -> OperationGraphBuilder:
+        """Add explicit dependency edges: dependencies -> target.
+
+        Args:
+            target: Operation that depends on others.
+            *dependencies: Operations that target depends on.
+            label: Optional edge labels.
+
+        Returns:
+            Self for chaining.
+
+        Raises:
+            ValueError: If target or any dependency not found.
+        """
+        if target not in self._nodes:
+            raise ValueError(f"Target operation '{target}' not found")
+
+        target_node = self._nodes[target]
+        resolved_label = [] if is_sentinel(label, {"none", "empty"}) else label
+
+        for dep_name in dependencies:
+            if dep_name not in self._nodes:
+                raise ValueError(f"Dependency operation '{dep_name}' not found")
+
+            dep_node = self._nodes[dep_name]
+
+            # Create edge: dependency -> target
+            edge = Edge(
+                head=dep_node.id,
+                tail=target_node.id,
+                label=resolved_label,
+            )
+            self.graph.add_edge(edge)
+
+        return self
+
+    def get(self, name: str) -> Operation:
+        """Get operation by name. Raises ValueError if not found."""
+        if name not in self._nodes:
+            raise ValueError(f"Operation '{name}' not found")
+        return self._nodes[name]
+
+    def get_by_id(self, operation_id: UUID) -> Operation | None:
+        """Get operation by UUID, or None if not in graph."""
+        node = self.graph.nodes.get(operation_id, None)
+        if isinstance(node, Operation):
+            return node
+        return None
+
+    def mark_executed(self, *names: str) -> OperationGraphBuilder:
+        """Mark operations as executed for incremental workflows. Returns self."""
+        for name in names:
+            if name in self._nodes:
+                self._executed.add(self._nodes[name].id)
+        return self
+
+    def get_unexecuted_nodes(self) -> list[Operation]:
+        """Return operations not marked as executed."""
+        return [op for op in self._nodes.values() if op.id not in self._executed]
+
+    def build(self) -> Graph:
+        """Validate and return the graph. Raises ValueError if cyclic."""
+        if not self.graph.is_acyclic():
+            raise ValueError("Operation graph has cycles - must be a DAG")
+        return self.graph
+
+    def clear(self) -> OperationGraphBuilder:
+        """Reset builder to empty state. Returns self."""
+        self.graph = Graph()
+        self._nodes = {}
+        self._executed = set()
+        self._current_heads = []
+        return self
+
+    def __repr__(self) -> str:
+        return (
+            f"OperationGraphBuilder("
+            f"operations={len(self._nodes)}, "
+            f"edges={len(self.graph.edges)}, "
+            f"executed={len(self._executed)})"
+        )
+
+
+# Alias for convenience
+Builder = OperationGraphBuilder