krons 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

krons/work/report.py

@@ -0,0 +1,268 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+"""Report - Multi-step workflow orchestration.
+
+A Report orchestrates multiple Forms based on data availability:
+- Schedules forms when their inputs become available
+- Groups forms by branch for sequential execution within branch
+- Propagates outputs between forms
+- Tracks overall workflow completion
+
+This is the scheduling layer that enables data-driven DAG execution.
+
+The Report pattern supports declarative workflow definition:
+    - Fields as class attributes (typed outputs)
+    - form_assignments DSL with branch/resource hints
+    - Implicit dependencies from data flow
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from typing import Any
+
+from pydantic import Field
+
+from krons.core import Element, Pile
+
+from .form import Form, parse_assignment
+
+__all__ = ("Report",)
+
+
+class Report(Element):
+    """Workflow orchestrator - schedules forms based on field availability.
+
+    A Report manages a collection of Forms, executing them as their
+    inputs become available. Forms are grouped by branch - forms on the
+    same branch execute sequentially, different branches can run in parallel.
+
+    Example (simple):
+        report = Report(
+            assignment="context -> final_score",
+            form_assignments=[
+                "context -> analysis",
+                "analysis -> score",
+                "score -> final_score",
+            ],
+        )
+        report.initialize(context="some input")
+
+        while not report.is_complete():
+            for form in report.next_forms():
+                await form.execute(ctx)
+                report.complete_form(form)
+
+    Example (with branches and resources):
+        class HiringBriefReport(Report):
+            role_classification: RoleClassification | None = None
+            strategic_context: StrategicContext | None = None
+
+            assignment: str = "job_input -> executive_summary"
+
+            form_assignments: list[str] = [
+                "classifier: job_input -> role_classification | api:fast",
+                "strategist: job_input, role_classification -> strategic_context | api:synthesis",
+                "writer: strategic_context -> executive_summary | api:reasoning",
+            ]
+
+    Attributes:
+        assignment: Overall workflow 'inputs -> final_outputs'
+        form_assignments: List of form assignments with optional branch/resource
+        input_fields: Workflow input fields
+        output_fields: Workflow output fields
+        forms: All forms in workflow
+        completed_forms: Forms that have finished
+        available_data: Current state of all field values
+    """
+
+    assignment: str = Field(
+        default="",
+        description="Overall workflow: 'inputs -> final_outputs'",
+    )
+    form_assignments: list[str] = Field(
+        default_factory=list,
+        description="List of form assignments: ['branch: a -> b | resource', ...]",
+    )
+
+    input_fields: list[str] = Field(default_factory=list)
+    output_fields: list[str] = Field(default_factory=list)
+
+    forms: Pile[Form] = Field(
+        default_factory=lambda: Pile(item_type=Form),
+        description="All forms in the workflow",
+    )
+    completed_forms: Pile[Form] = Field(
+        default_factory=lambda: Pile(item_type=Form),
+        description="Completed forms",
+    )
+    available_data: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Current state of all field values",
+    )
+
+    # Branch tracking: branch_name -> list of form IDs in order
+    _branch_forms: dict[str, list[Form]] = {}
+    # Track last completed form per branch for sequential execution
+    _branch_progress: dict[str, int] = {}
+
+    def model_post_init(self, _: Any) -> None:
+        """Parse assignment and create forms."""
+        self._branch_forms = defaultdict(list)
+        self._branch_progress = defaultdict(int)
+
+        if not self.assignment:
+            return
+
+        # Parse overall assignment
+        self.input_fields, self.output_fields = parse_assignment(self.assignment)
+
+        # Create forms from form_assignments
+        for fa in self.form_assignments:
+            form = Form(assignment=fa)
+            self.forms.include(form)
+
+            # Track by branch
+            branch = form.branch or "_default"
+            self._branch_forms[branch].append(form)
+
+    def initialize(self, **inputs: Any) -> None:
+        """Provide initial input data.
+
+        Args:
+            **inputs: Initial field values
+
+        Raises:
+            ValueError: If required input is missing
+        """
+        for field in self.input_fields:
+            if field not in inputs:
+                raise ValueError(f"Missing required input: '{field}'")
+            self.available_data[field] = inputs[field]
+
+    def next_forms(self) -> list[Form]:
+        """Get forms that are ready to execute.
+
+        Forms with explicit branches execute sequentially within their branch.
+        Forms without branches (None) execute in parallel based on data availability.
+
+        Returns:
+            List of forms with all inputs available and not yet filled
+        """
+        ready = []
+
+        for branch, forms in self._branch_forms.items():
+            if branch == "_default":
+                # No explicit branch - parallel execution based on data
+                for form in forms:
+                    if form.filled:
+                        continue
+                    form.available_data = self.available_data.copy()
+                    if form.is_workable():
+                        ready.append(form)
+            else:
+                # Explicit branch - sequential execution
+                progress = self._branch_progress[branch]
+
+                # Only consider the next form in this branch
+                if progress < len(forms):
+                    form = forms[progress]
+                    if form.filled:
+                        # Already done, advance progress
+                        self._branch_progress[branch] += 1
+                        continue
+
+                    form.available_data = self.available_data.copy()
+                    if form.is_workable():
+                        ready.append(form)
+
+        return ready
+
+    def complete_form(self, form: Form) -> None:
+        """Mark a form as completed and update available data.
+
+        Args:
+            form: The completed form
+
+        Raises:
+            ValueError: If form is not filled
+        """
+        if not form.filled:
+            raise ValueError("Form is not filled")
+
+        self.completed_forms.include(form)
+
+        # Advance branch progress
+        branch = form.branch or "_default"
+        if branch in self._branch_forms:
+            forms = self._branch_forms[branch]
+            progress = self._branch_progress[branch]
+            if progress < len(forms) and forms[progress].id == form.id:
+                self._branch_progress[branch] += 1
+
+        # Update available data with form outputs
+        output_data = form.get_output_data()
+        self.available_data.update(output_data)
+
+    def is_complete(self) -> bool:
+        """Check if all output fields are available.
+
+        Returns:
+            True if workflow is complete
+        """
+        return all(field in self.available_data for field in self.output_fields)
+
+    def get_deliverable(self) -> dict[str, Any]:
+        """Get final output values.
+
+        Returns:
+            Dict of output field values
+        """
+        return {f: self.available_data.get(f) for f in self.output_fields}
+
+    @property
+    def progress(self) -> tuple[int, int]:
+        """Get progress as (completed, total).
+
+        Returns:
+            Tuple of (completed forms, total forms)
+        """
+        return len(self.completed_forms), len(self.forms)
+
+    def get_forms_by_branch(self, branch: str) -> list[Form]:
+        """Get all forms for a specific branch.
+
+        Args:
+            branch: Branch name
+
+        Returns:
+            List of forms on that branch (in order)
+        """
+        return list(self._branch_forms.get(branch, []))
+
+    def get_forms_by_resource(self, resource: str) -> list[Form]:
+        """Get all forms requiring a specific resource.
+
+        Args:
+            resource: Resource hint (e.g., 'api:fast')
+
+        Returns:
+            List of forms with that resource hint
+        """
+        return [f for f in self.forms if f.resource == resource]
+
+    @property
+    def branches(self) -> list[str]:
+        """Get all branch names in this report."""
+        return list(self._branch_forms.keys())
+
+    @property
+    def resources(self) -> set[str]:
+        """Get all resource hints used in this report."""
+        return {f.resource for f in self.forms if f.resource}
+
+    def __repr__(self) -> str:
+        completed, total = self.progress
+        branches = len(self._branch_forms)
+        return f"Report('{self.assignment}', {completed}/{total} forms, {branches} branches)"

krons/work/rules/__init__.py

@@ -0,0 +1,47 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+"""Rules module: validation rules with auto-correction support.
+
+Core exports:
+- Rule, RuleParams, RuleQualifier: Base rule classes
+- ValidationError: Validation failure exception
+- Validator: Spec-aware validation orchestrator
+- RuleRegistry: Type-to-rule mapping with inheritance
+- Common rules: StringRule, NumberRule, BooleanRule, ChoiceRule, MappingRule, BaseModelRule
+"""
+
+from krons.errors import ValidationError
+
+from .common import (
+    BaseModelRule,
+    BooleanRule,
+    ChoiceRule,
+    MappingRule,
+    NumberRule,
+    StringRule,
+)
+from .registry import RuleRegistry, get_default_registry, reset_default_registry
+from .rule import Rule, RuleParams, RuleQualifier
+from .validator import Validator
+
+__all__ = (
+    # Base classes
+    "Rule",
+    "RuleParams",
+    "RuleQualifier",
+    "ValidationError",
+    # Validator
+    "Validator",
+    # Registry
+    "RuleRegistry",
+    "get_default_registry",
+    "reset_default_registry",
+    # Common rules
+    "BaseModelRule",
+    "BooleanRule",
+    "ChoiceRule",
+    "MappingRule",
+    "NumberRule",
+    "StringRule",
+)

{kronos/enforcement → krons/work/rules}/common/boolean.py

@@ -50,7 +50,9 @@ class BooleanRule(Rule):
             ValueError: If not a boolean
         """
         if not isinstance(v, bool):
-            raise ValueError(f"Invalid boolean value: expected bool, got {type(v).__name__}")
+            raise ValueError(
+                f"Invalid boolean value: expected bool, got {type(v).__name__}"
+            )
 
     async def perform_fix(self, v: Any, _t: type) -> Any:
         """Attempt to convert value to boolean.

{kronos/enforcement → krons/work/rules}/common/choice.py

@@ -58,7 +58,9 @@ class ChoiceRule(Rule):
         self.case_sensitive = case_sensitive
 
         if not case_sensitive:
-            self._lower_map = {str(c).lower(): c for c in self.choices if isinstance(c, str)}
+            self._lower_map = {
+                str(c).lower(): c for c in self.choices if isinstance(c, str)
+            }
 
     async def validate(self, v: Any, t: type, **kw) -> None:
         """Validate that value is in allowed choices (exact match only).
@@ -72,7 +74,9 @@ class ChoiceRule(Rule):
         if v in self.choices:
             return
 
-        raise ValueError(f"Invalid choice: {v} not in {sorted(str(c) for c in self.choices)}")
+        raise ValueError(
+            f"Invalid choice: {v} not in {sorted(str(c) for c in self.choices)}"
+        )
 
     async def perform_fix(self, v: Any, _t: type) -> Any:
         """Attempt to fix value to closest choice.
@@ -94,4 +98,6 @@ class ChoiceRule(Rule):
             if v_lower in self._lower_map:
                 return self._lower_map[v_lower]
 
-        raise ValueError(f"Cannot fix choice: {v} not in {sorted(str(c) for c in self.choices)}")
+        raise ValueError(
+            f"Cannot fix choice: {v} not in {sorted(str(c) for c in self.choices)}"
+        )

{kronos/enforcement → krons/work/rules}/common/number.py

@@ -66,7 +66,9 @@ class NumberRule(Rule):
             ValueError: If not a number or constraints violated
         """
         if not isinstance(v, (int, float)):
-            raise ValueError(f"Invalid number value: expected int or float, got {type(v).__name__}")
+            raise ValueError(
+                f"Invalid number value: expected int or float, got {type(v).__name__}"
+            )
 
         if self.ge is not None and v < self.ge:
             raise ValueError(f"Number too small: {v} < {self.ge}")

{kronos/enforcement → krons/work/rules}/common/string.py

@@ -103,14 +103,18 @@ class StringRule(Rule):
             ValueError: If not a string or constraints violated
         """
         if not isinstance(v, str):
-            raise ValueError(f"Invalid string value: expected str, got {type(v).__name__}")
+            raise ValueError(
+                f"Invalid string value: expected str, got {type(v).__name__}"
+            )
 
         if self.min_length is not None and len(v) < self.min_length:
             raise ValueError(
                 f"String too short: got {len(v)} characters, minimum {self.min_length}"
             )
         if self.max_length is not None and len(v) > self.max_length:
-            raise ValueError(f"String too long: got {len(v)} characters, maximum {self.max_length}")
+            raise ValueError(
+                f"String too long: got {len(v)} characters, maximum {self.max_length}"
+            )
 
         if self._compiled_pattern is not None:
             if len(v) > self.regex_max_input_length:
@@ -119,7 +123,9 @@ class StringRule(Rule):
                     f"maximum {self.regex_max_input_length}"
                 )
             if not self._compiled_pattern.match(v):
-                raise ValueError(f"String does not match required pattern: {self.pattern}")
+                raise ValueError(
+                    f"String does not match required pattern: {self.pattern}"
+                )
 
     async def perform_fix(self, v: Any, t: type) -> Any:
         """Attempt to convert value to string and re-validate.

{kronos/enforcement → krons/work/rules}/rule.py

@@ -8,8 +8,8 @@ from dataclasses import dataclass, field
 from enum import IntEnum, auto
 from typing import Any
 
-from kronos.errors import ValidationError
-from kronos.types import Params
+from krons.core.types import Params
+from krons.errors import ValidationError
 
 __all__ = ("Rule", "RuleParams", "RuleQualifier", "ValidationError")
 

{kronos/enforcement → krons/work/rules}/validator.py

@@ -7,14 +7,16 @@ 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 krons.core.types import is_sentinel, not_sentinel
+from krons.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
+    from pydantic import BaseModel
+
+    from krons.core.specs import Operable, Spec
 
 __all__ = ("Validator",)
 
@@ -29,7 +31,9 @@ class Validator:
     ):
         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
+            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
@@ -141,7 +145,9 @@ class Validator:
                     raise ValidationError(error_msg)
             else:
                 try:
-                    value = await rule.invoke(field_name, value, spec.base_type, auto_fix=auto_fix)
+                    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
@@ -171,14 +177,20 @@ class Validator:
 
         return value
 
-    async def validate_operable(
+    async def validate(
         self,
         data: dict[str, Any],
         operable: Operable,
         capabilities: set[str] | None = None,
         auto_fix: bool = True,
         strict: bool = True,
+        structure: type[BaseModel] | None = None,
     ) -> dict[str, Any]:
+        if not_sentinel(capabilities, {"none"}) and not capabilities.issubset(
+            operable.allowed()
+        ):
+            raise ValidationError("Capabilities exceed operable's allowed set")
+
         capabilities = capabilities or operable.allowed()
         validated: dict[str, Any] = {}
 
@@ -195,4 +207,7 @@ class Validator:
                 spec, value, auto_fix=auto_fix, strict=strict
             )
 
+        if structure is not None:
+            validated = operable.validate_instance(structure, validated)
+
         return validated

{kronos/enforcement → krons/work}/service.py

@@ -12,9 +12,9 @@ from typing import Any
 
 from pydantic import Field, PrivateAttr
 
-from kronos.services import ServiceBackend, ServiceConfig
+from krons.resource import ResourceBackend, ResourceConfig
+from krons.work.operations.context import RequestContext
 
-from .context import RequestContext
 from .policy import EnforcementLevel, PolicyEngine, PolicyResolver
 
 logger = logging.getLogger(__name__)
@@ -28,7 +28,7 @@ __all__ = (
 )
 
 
-class KronConfig(ServiceConfig):
+class KronConfig(ResourceConfig):
     """Configuration for KronService.
 
     Attributes:
@@ -135,7 +135,7 @@ def get_action_meta(handler: Callable) -> ActionMeta | None:
 # =============================================================================
 
 
-class KronService(ServiceBackend):
+class KronService(ResourceBackend):
     """Service backend with typed actions.
 
     Subclasses implement action handlers with @action decorator.
@@ -168,7 +168,9 @@ class KronService(ServiceBackend):
     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)
+    _action_registry: dict[str, tuple[Callable, ActionMeta]] = PrivateAttr(
+        default_factory=dict
+    )
 
     def __init__(
         self,
@@ -193,6 +195,9 @@ class KronService(ServiceBackend):
     def _register_actions(self) -> None:
         """Scan for @action decorated methods and register them."""
         for name in dir(self):
+            # Skip dunder attributes to avoid Pydantic deprecation warnings
+            if name.startswith("__"):
+                continue
             if name.startswith("_"):
                 method = getattr(self, name, None)
                 if method and callable(method):
@@ -287,7 +292,9 @@ class KronService(ServiceBackend):
 
         # 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)
+            options = self.config.operable.validate_instance(
+                meta._options_type, options
+            )
 
         # Execute handler
         result = await handler(options, ctx)
@@ -349,7 +356,9 @@ class KronService(ServiceBackend):
 
             for result in results:
                 if EnforcementLevel.is_blocking(result):
-                    raise PermissionError(f"Policy {result.policy_id} blocked: {result.message}")
+                    raise PermissionError(
+                        f"Policy {result.policy_id} blocked: {result.message}"
+                    )
 
         except PermissionError:
             raise