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

{kronos/enforcement → krons/work/operations}/context.py

@@ -11,11 +11,11 @@ from datetime import datetime
 from typing import TYPE_CHECKING, Any, Protocol
 from uuid import UUID, uuid4
 
-from kronos.types.base import DataClass
-from kronos.types.identity import ID
+from krons.core.types.base import DataClass
+from krons.core.types.identity import ID
 
 if TYPE_CHECKING:
-    from kronos.session import Branch, Session
+    from krons.session import Branch, Session
 
 __all__ = ("QueryFn", "RequestContext")
 
@@ -85,7 +85,7 @@ class RequestContext(DataClass):
     name: str
     id: UUID = field(default_factory=uuid4)
     session_id: ID[Session] | None = None
-    branch_id: ID[Branch] | None = None
+    branch: ID[Branch] | str | None = None
     metadata: dict[str, Any] = field(default_factory=dict)
     conn: Any | None = None
     query_fn: QueryFn | None = None
@@ -95,7 +95,7 @@ class RequestContext(DataClass):
         self,
         name: str,
         session_id: ID[Session] | None = None,
-        branch_id: ID[Branch] | None = None,
+        branch: ID[Branch] | str | None = None,
         id: UUID | None = None,
         conn: Any | None = None,
         query_fn: QueryFn | None = None,
@@ -105,7 +105,7 @@ class RequestContext(DataClass):
         self.name = name
         self.id = id or uuid4()
         self.session_id = session_id
-        self.branch_id = branch_id
+        self.branch = branch
         self.conn = conn
         self.query_fn = query_fn
         self.now = now
@@ -127,3 +127,34 @@ class RequestContext(DataClass):
             raise AttributeError(
                 f"'{type(self).__name__}' has no attribute '{name}'"
             ) from None
+
+    async def get_session(self) -> Session | None:
+        """Get the Session object.
+
+        Checks bound reference first (set by Operation.invoke),
+        then falls back to global registry lookup via session_id.
+
+        Returns None if no session available.
+        """
+        if "_bound_session" in self.metadata:
+            return self.metadata["_bound_session"]
+        if self.session_id is None:
+            return None
+        from krons.session.registry import get_session
+
+        return await get_session(self.session_id)
+
+    async def get_branch(self) -> Branch | None:
+        """Get the Branch object.
+
+        Checks bound reference first (set by Operation.invoke),
+        then falls back to session lookup via branch identifier.
+
+        Returns None if no branch available.
+        """
+        if "_bound_branch" in self.metadata:
+            return self.metadata["_bound_branch"]
+        session = await self.get_session()
+        if session is None or self.branch is None:
+            return None
+        return session.branches.get(self.branch)

{kronos → krons/work}/operations/flow.py

@@ -15,15 +15,15 @@ from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any
 from uuid import UUID
 
-from kronos.core import EventStatus, Graph
-from kronos.types import Undefined, UndefinedType, is_sentinel
-from kronos.utils import concurrency
-from kronos.utils.concurrency import CapacityLimiter, CompletionStream
+from krons.core import EventStatus, Graph
+from krons.core.types import Undefined, UndefinedType, is_sentinel
+from krons.utils import concurrency
+from krons.utils.concurrency import CapacityLimiter, CompletionStream
 
 from .node import Operation
 
 if TYPE_CHECKING:
-    from kronos.session import Branch, Session
+    from krons.session import Branch, Session
 
 logger = logging.getLogger(__name__)
 
@@ -94,8 +94,12 @@ class DependencyAwareExecutor:
         """
         self.session = session
         self.graph = graph
-        resolved_max_concurrent = None if is_sentinel(max_concurrent) else max_concurrent
-        resolved_default_branch = None if is_sentinel(default_branch) else default_branch
+        resolved_max_concurrent = (
+            None if is_sentinel(max_concurrent) else max_concurrent
+        )
+        resolved_default_branch = (
+            None if is_sentinel(default_branch) else default_branch
+        )
         self.max_concurrent = resolved_max_concurrent
         self.stop_on_error = stop_on_error
         self.verbose = verbose
@@ -107,7 +111,9 @@ class DependencyAwareExecutor:
         self.operation_branches: dict[UUID, Branch | None] = {}
 
         self._limiter: CapacityLimiter | None = (
-            CapacityLimiter(resolved_max_concurrent) if resolved_max_concurrent else None
+            CapacityLimiter(resolved_max_concurrent)
+            if resolved_max_concurrent
+            else None
         )
 
         for node in graph.nodes:
@@ -258,7 +264,9 @@ class DependencyAwareExecutor:
                     self.operation_branches[node.id] = default_branch
 
         if self.verbose:
-            logger.debug("Pre-allocated branches for %d operations", len(self.operation_branches))
+            logger.debug(
+                "Pre-allocated branches for %d operations", len(self.operation_branches)
+            )
 
     async def _execute_operation(self, operation: Operation) -> Operation:
         """Execute single operation: wait deps -> acquire slot -> invoke -> signal."""

krons/work/operations/node.py

@@ -0,0 +1,103 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+"""Operation: executable graph node bridging session to handler.
+
+Operation.invoke() creates a RequestContext from the bound session/branch
+and calls the registered handler with (params, ctx). Handlers never need
+to know about the factory pattern — they receive a clean RequestContext.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from pydantic import Field, PrivateAttr
+
+from krons.core import Event, Node
+
+from .context import RequestContext
+
+if TYPE_CHECKING:
+    from krons.session import Branch, Session
+
+__all__ = ("Operation",)
+
+
+class Operation(Node, Event):
+    """Executable operation node.
+
+    Bridges session.conduct() to handler(params, ctx) by:
+    1. Storing bound session/branch references
+    2. Creating RequestContext with those references
+    3. Looking up the handler from session.operations registry
+    4. Calling handler(params, ctx)
+
+    The result is stored in execution.response (via Event.invoke).
+    """
+
+    operation_type: str
+    parameters: dict[str, Any] | Any = Field(
+        default_factory=dict,
+        description="Operation parameters (Params dataclass, dict, or model)",
+    )
+
+    _session: Any = PrivateAttr(default=None)
+    _branch: Any = PrivateAttr(default=None)
+    _verbose: bool = PrivateAttr(default=False)
+
+    def bind(self, session: Session, branch: Branch) -> Operation:
+        """Bind session and branch for execution.
+
+        Must be called before invoke() if not using Session.conduct().
+
+        Args:
+            session: Session with operations registry and services.
+            branch: Branch for message context.
+
+        Returns:
+            Self for chaining.
+        """
+        self._session = session
+        self._branch = branch
+        return self
+
+    def _require_binding(self) -> tuple[Session, Branch]:
+        """Return bound (session, branch) tuple or raise RuntimeError if unbound."""
+        if self._session is None or self._branch is None:
+            raise RuntimeError(
+                "Operation not bound to session/branch. "
+                "Use operation.bind(session, branch) or session.conduct(...)"
+            )
+        return self._session, self._branch
+
+    async def _invoke(self) -> Any:
+        """Execute handler via session's operation registry.
+
+        Creates a RequestContext with bound session/branch references
+        and calls handler(params, ctx). Called by Event.invoke().
+
+        Returns:
+            Handler result (stored in execution.response).
+
+        Raises:
+            RuntimeError: If not bound.
+            KeyError: If operation_type not registered.
+        """
+        session, branch = self._require_binding()
+        handler = session.operations.get(self.operation_type)
+
+        ctx = RequestContext(
+            name=self.operation_type,
+            session_id=session.id,
+            branch=branch.name or str(branch.id),
+            _bound_session=session,
+            _bound_branch=branch,
+            _verbose=self._verbose,
+        )
+
+        return await handler(self.parameters, ctx)
+
+    def __repr__(self) -> str:
+        bound = "bound" if self._session is not None else "unbound"
+        return f"Operation(type={self.operation_type}, status={self.execution.status.value}, {bound})"

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()})"

{kronos/specs → krons/work}/phrase.py

@@ -6,7 +6,7 @@ A Phrase wraps an async handler with:
 - Validation via Operable
 
 Usage with decorator (custom handler):
-    from kronos.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 kronos.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 kronos.types import Unset, is_unset
-from kronos.utils.sql import validate_identifier
+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.

{kronos/enforcement → krons/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 kronos.enforcement.context import RequestContext
-from kronos.specs.catalog._enforcement import EnforcementLevel
-from kronos.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",