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

krons/work/operations/registry.py

@@ -0,0 +1,103 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+"""Per-session operation handler registry.
+
+Maps operation names to async handlers. Instantiated per-Session
+for isolation, testability, and per-session customization.
+
+Handler signature: async handler(params, ctx: RequestContext) -> result
+Operation._invoke() creates the RequestContext from bound session/branch.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+__all__ = ("OperationHandler", "OperationRegistry")
+
+OperationHandler = Callable[..., Awaitable[Any]]
+"""Handler signature: async (params, ctx: RequestContext) -> result"""
+
+
+class OperationRegistry:
+    """Map operation names to async handler functions.
+
+    Per-session registry (not global) for isolation and testability.
+
+    Example:
+        from krons.agent.operations import generate, structure, operate
+
+        registry = OperationRegistry()
+        registry.register("generate", generate)
+        registry.register("structure", structure)
+        registry.register("operate", operate)
+
+        # Called by Operation._invoke() — users call session.conduct()
+        handler = registry.get("generate")
+        result = await handler(params, ctx)
+    """
+
+    def __init__(self):
+        """Initialize empty registry."""
+        self._handlers: dict[str, OperationHandler] = {}
+
+    def register(
+        self,
+        operation_name: str,
+        handler: OperationHandler,
+        *,
+        override: bool = False,
+    ) -> None:
+        """Register handler for operation name.
+
+        Args:
+            operation_name: Lookup key (e.g. "generate", "operate").
+            handler: Async (params, ctx) -> result.
+            override: Allow replacing existing. Default False.
+
+        Raises:
+            ValueError: If name exists and override=False.
+        """
+        if operation_name in self._handlers and not override:
+            raise ValueError(
+                f"Operation '{operation_name}' already registered. "
+                "Use override=True to replace."
+            )
+        self._handlers[operation_name] = handler
+
+    def get(self, operation_name: str) -> OperationHandler:
+        """Get handler by name. Raises KeyError with available names if not found."""
+        if operation_name not in self._handlers:
+            raise KeyError(
+                f"Operation '{operation_name}' not registered. "
+                f"Available: {self.list_names()}"
+            )
+        return self._handlers[operation_name]
+
+    def has(self, operation_name: str) -> bool:
+        """Check if name is registered."""
+        return operation_name in self._handlers
+
+    def unregister(self, operation_name: str) -> bool:
+        """Remove registration. Returns True if existed."""
+        if operation_name in self._handlers:
+            del self._handlers[operation_name]
+            return True
+        return False
+
+    def list_names(self) -> list[str]:
+        """Return all registered operation names."""
+        return list(self._handlers.keys())
+
+    def __contains__(self, operation_name: str) -> bool:
+        """Support 'name in registry' syntax."""
+        return operation_name in self._handlers
+
+    def __len__(self) -> int:
+        """Count of registered operations."""
+        return len(self._handlers)
+
+    def __repr__(self) -> str:
+        return f"OperationRegistry(operations={self.list_names()})"

krons/{specs → work}/phrase.py

@@ -6,7 +6,7 @@ A Phrase wraps an async handler with:
 - Validation via Operable
 
 Usage with decorator (custom handler):
-    from krons.specs import Operable, phrase
+    from krons.core.specs import Operable, phrase
 
     consent_operable = Operable([
         Spec("subject_id", UUID),
@@ -25,7 +25,7 @@ Usage with decorator (custom handler):
     result = await verify_consent({"subject_id": id, "scope": "background"}, ctx)
 
 Usage with CrudPattern (declarative):
-    from krons.specs import Operable, phrase, CrudPattern
+    from krons.core.specs import Operable, phrase, CrudPattern
 
     def check_has_consent(row):
         return {"has_consent": row["status"] in {"active"} if row else False}
@@ -48,12 +48,14 @@ from collections.abc import Awaitable, Callable, Mapping
 from dataclasses import dataclass
 from enum import Enum
 from types import MappingProxyType
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
-from krons.types import Unset, is_unset
+from krons.core.specs.operable import Operable
+from krons.core.types import Unset, is_unset
 from krons.utils.sql import validate_identifier
 
-from .operable import Operable
+if TYPE_CHECKING:
+    from krons.work.operations.node import Operation
 
 __all__ = ("CrudPattern", "CrudOperation", "Phrase", "phrase")
 
@@ -111,18 +113,31 @@ class CrudPattern:
             object.__setattr__(self, "lookup", frozenset(self.lookup))
         # Normalize None mappings to immutable empty maps; freeze mutable dicts
         object.__setattr__(
-            self, "filters",
-            _EMPTY_MAP if self.filters is None else MappingProxyType(dict(self.filters)),
+            self,
+            "filters",
+            (
+                _EMPTY_MAP
+                if self.filters is None
+                else MappingProxyType(dict(self.filters))
+            ),
         )
         object.__setattr__(
-            self, "set_fields",
-            _EMPTY_MAP if self.set_fields is None
-            else MappingProxyType(dict(self.set_fields)),
+            self,
+            "set_fields",
+            (
+                _EMPTY_MAP
+                if self.set_fields is None
+                else MappingProxyType(dict(self.set_fields))
+            ),
         )
         object.__setattr__(
-            self, "defaults",
-            _EMPTY_MAP if self.defaults is None
-            else MappingProxyType(dict(self.defaults)),
+            self,
+            "defaults",
+            (
+                _EMPTY_MAP
+                if self.defaults is None
+                else MappingProxyType(dict(self.defaults))
+            ),
         )
 
 
@@ -307,6 +322,108 @@ class Phrase:
         )
         return self._result_type
 
+    # --- Form-like interface ---
+
+    @property
+    def input_fields(self) -> list[str]:
+        """Input field names (Form-compatible interface)."""
+        return list(self.inputs)
+
+    @property
+    def output_fields(self) -> list[str]:
+        """Output field names (Form-compatible interface)."""
+        return list(self.outputs)
+
+    def is_workable(self, available_data: dict[str, Any]) -> bool:
+        """Check if all inputs are available in data dict.
+
+        Enables Form/Report-style scheduling based on data availability.
+        """
+        return all(field in available_data for field in self.inputs)
+
+    def extract_inputs(self, available_data: dict[str, Any]) -> dict[str, Any]:
+        """Extract input values from available data.
+
+        Returns:
+            Dict with only the fields declared as inputs.
+
+        Raises:
+            KeyError: If any required input is missing.
+        """
+        return {field: available_data[field] for field in self.inputs}
+
+    # --- Operation bridge ---
+
+    def as_operation(
+        self,
+        options: dict[str, Any] | None = None,
+        *,
+        available_data: dict[str, Any] | None = None,
+        ctx: Any = None,
+        **metadata,
+    ) -> "Operation":
+        """Create an Operation that invokes this phrase.
+
+        The Operation can participate in DAG flow while preserving
+        the phrase's typed I/O semantics.
+
+        Args:
+            options: Direct input values (takes precedence)
+            available_data: Data dict to extract inputs from (if options not given)
+            ctx: Execution context passed to phrase handler
+            **metadata: Additional metadata for Operation
+
+        Returns:
+            PhraseOperation instance ready for DAG execution.
+
+        Example:
+            # Direct options
+            op = phrase.as_operation({"subject_id": id, "scope": "read"})
+
+            # From available data (Form/Report pattern)
+            op = phrase.as_operation(available_data=report.available_data)
+
+            # Build DAG
+            graph = Graph()
+            graph.add_node(phrase1.as_operation({"input": "x"}))
+            await flow(session, graph)
+        """
+        from krons.work.operations.node import Operation
+
+        # Resolve options
+        if options is not None:
+            resolved_options = dict(options)
+        elif available_data is not None:
+            if not self.is_workable(available_data):
+                missing = [f for f in self.inputs if f not in available_data]
+                raise ValueError(f"Missing required inputs: {missing}")
+            resolved_options = self.extract_inputs(available_data)
+        else:
+            raise ValueError("Either options or available_data must be provided")
+
+        # Create closure-based operation that bypasses registry
+        phrase = self
+        bound_ctx = ctx
+
+        class PhraseOperation(Operation):
+            """Operation wrapping a Phrase for direct invocation."""
+
+            async def _invoke(self) -> Any:
+                # Direct phrase invocation - no registry lookup
+                return await phrase(self.parameters, bound_ctx)
+
+        return PhraseOperation(
+            operation_type=self.name,
+            parameters=resolved_options,
+            metadata={
+                "name": self.name,
+                "phrase": True,
+                "input_fields": self.input_fields,
+                "output_fields": self.output_fields,
+                **metadata,
+            },
+        )
+
 
 def _to_pascal(snake_name: str) -> str:
     """Convert snake_case name to PascalCase.

krons/{enforcement → work}/policy.py

@@ -13,9 +13,9 @@ from collections.abc import Sequence
 from dataclasses import dataclass, field
 from typing import Any, Protocol, runtime_checkable
 
-from krons.enforcement.context import RequestContext
-from krons.specs.catalog._enforcement import EnforcementLevel
-from krons.types.base import DataClass
+from krons.core.specs.catalog._enforcement import EnforcementLevel
+from krons.core.types.base import DataClass
+from krons.work.operations.context import RequestContext
 
 __all__ = (
     "EnforcementLevel",

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",
+)

krons/{enforcement → 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.

krons/{enforcement → 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)}"
+        )

krons/{enforcement → 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}")