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

krons/work/form.py

@@ -0,0 +1,305 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+"""Form - Data binding and scheduling for work units.
+
+A Form represents an instantiated work unit with:
+- Data binding (input values)
+- Execution state tracking (filled, workable)
+- Optional Phrase reference for typed I/O
+
+Forms are the stateful layer between Phrase (definition) and Operation (execution).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from pydantic import Field
+
+from krons.core import Element
+
+if TYPE_CHECKING:
+    from .phrase import Phrase
+
+__all__ = ("Form", "ParsedAssignment", "parse_assignment", "parse_full_assignment")
+
+
+@dataclass
+class ParsedAssignment:
+    """Parsed form assignment with all components.
+
+    Attributes:
+        branch: Branch/worker name (e.g., "classifier1")
+        inputs: Input field names
+        outputs: Output field names
+        resource: Resource hint (e.g., "api:fast")
+        raw: Original assignment string
+    """
+
+    branch: str | None
+    inputs: list[str]
+    outputs: list[str]
+    resource: str | None
+    raw: str
+
+
+def parse_assignment(assignment: str) -> tuple[list[str], list[str]]:
+    """Parse 'inputs -> outputs' assignment DSL (simple form).
+
+    Args:
+        assignment: DSL string like "a, b -> c, d"
+
+    Returns:
+        Tuple of (input_fields, output_fields)
+
+    Raises:
+        ValueError: If assignment format is invalid
+    """
+    parsed = parse_full_assignment(assignment)
+    return parsed.inputs, parsed.outputs
+
+
+def parse_full_assignment(assignment: str) -> ParsedAssignment:
+    """Parse full assignment DSL with branch and resource hints.
+
+    Format: "branch: inputs -> outputs | resource"
+
+    Examples:
+        "a, b -> c"                           # Simple
+        "classifier: job -> role | api:fast"  # Full
+        "writer: context -> summary"          # Branch, no resource
+
+    Args:
+        assignment: DSL string
+
+    Returns:
+        ParsedAssignment with all components
+
+    Raises:
+        ValueError: If format is invalid
+    """
+    raw = assignment.strip()
+    branch = None
+    resource = None
+
+    # Extract resource hint (after |)
+    if "|" in raw:
+        main_part, resource_part = raw.rsplit("|", 1)
+        resource = resource_part.strip()
+        raw = main_part.strip()
+
+    # Extract branch name (before :)
+    if ":" in raw:
+        # Check it's not just inside the field list
+        colon_idx = raw.find(":")
+        arrow_idx = raw.find("->")
+        if arrow_idx == -1 or colon_idx < arrow_idx:
+            branch_part, raw = raw.split(":", 1)
+            branch = branch_part.strip()
+            raw = raw.strip()
+
+    # Parse inputs -> outputs
+    if "->" not in raw:
+        raise ValueError(f"Invalid assignment syntax (missing '->'): {assignment}")
+
+    parts = raw.split("->")
+    if len(parts) != 2:
+        raise ValueError(f"Invalid assignment syntax: {assignment}")
+
+    inputs = [f.strip() for f in parts[0].split(",") if f.strip()]
+    outputs = [f.strip() for f in parts[1].split(",") if f.strip()]
+
+    return ParsedAssignment(
+        branch=branch,
+        inputs=inputs,
+        outputs=outputs,
+        resource=resource,
+        raw=assignment,
+    )
+
+
+class Form(Element):
+    """Data binding container for work units.
+
+    A Form binds input data and tracks execution state. It can be created:
+    1. From a Phrase (typed I/O)
+    2. From an assignment string (dynamic fields)
+
+    Assignment DSL supports full format:
+        "branch: inputs -> outputs | resource"
+
+    Examples:
+        "a, b -> c"                           # Simple
+        "classifier: job -> role | api:fast"  # Full with branch and resource
+        "writer: context -> summary"          # Branch, no resource
+
+    Attributes:
+        assignment: DSL string 'branch: inputs -> outputs | resource'
+        branch: Worker/branch name for routing
+        resource: Resource hint for capability matching
+        input_fields: Fields required as inputs
+        output_fields: Fields produced as outputs
+        available_data: Current data values
+        output: Execution result
+        filled: Whether form has been executed
+        phrase: Optional Phrase reference for typed execution
+    """
+
+    assignment: str = Field(
+        default="",
+        description="Assignment DSL: 'branch: inputs -> outputs | resource'",
+    )
+    branch: str | None = Field(
+        default=None,
+        description="Worker/branch name for routing",
+    )
+    resource: str | None = Field(
+        default=None,
+        description="Resource hint (e.g., 'api:fast')",
+    )
+    input_fields: list[str] = Field(default_factory=list)
+    output_fields: list[str] = Field(default_factory=list)
+    available_data: dict[str, Any] = Field(default_factory=dict)
+    output: Any = Field(default=None)
+    filled: bool = Field(default=False)
+
+    # Optional phrase reference (set via from_phrase())
+    _phrase: "Phrase | None" = None
+
+    def model_post_init(self, _: Any) -> None:
+        """Parse assignment to derive fields if not already set."""
+        if self.assignment and not self.input_fields and not self.output_fields:
+            parsed = parse_full_assignment(self.assignment)
+            self.input_fields = parsed.inputs
+            self.output_fields = parsed.outputs
+            if parsed.branch and self.branch is None:
+                self.branch = parsed.branch
+            if parsed.resource and self.resource is None:
+                self.resource = parsed.resource
+
+    @classmethod
+    def from_phrase(
+        cls,
+        phrase: "Phrase",
+        **initial_data: Any,
+    ) -> "Form":
+        """Create Form from a Phrase with optional initial data.
+
+        Args:
+            phrase: Phrase defining typed I/O
+            **initial_data: Initial input values
+
+        Returns:
+            Form bound to the phrase
+        """
+        form = cls(
+            assignment=f"{', '.join(phrase.inputs)} -> {', '.join(phrase.outputs)}",
+            input_fields=list(phrase.inputs),
+            output_fields=list(phrase.outputs),
+            available_data=dict(initial_data),
+        )
+        form._phrase = phrase
+        return form
+
+    @property
+    def phrase(self) -> "Phrase | None":
+        """Get bound phrase if any."""
+        return self._phrase
+
+    def is_workable(self) -> bool:
+        """Check if form is ready for execution.
+
+        Returns:
+            True if all inputs available and not already filled
+        """
+        if self.filled:
+            return False
+
+        for field in self.input_fields:
+            if field not in self.available_data:
+                return False
+            if self.available_data[field] is None:
+                return False
+
+        return True
+
+    def get_inputs(self) -> dict[str, Any]:
+        """Extract input data for execution.
+
+        Returns:
+            Dict of input field values
+        """
+        return {
+            f: self.available_data[f]
+            for f in self.input_fields
+            if f in self.available_data
+        }
+
+    def fill(self, **data: Any) -> None:
+        """Add data to available_data.
+
+        Args:
+            **data: Field values to add
+        """
+        self.available_data.update(data)
+
+    def set_output(self, output: Any) -> None:
+        """Mark form as filled with output.
+
+        Args:
+            output: Execution result
+        """
+        self.output = output
+        self.filled = True
+
+        # Extract output field values from result
+        if output is not None:
+            for field in self.output_fields:
+                if hasattr(output, field):
+                    self.available_data[field] = getattr(output, field)
+                elif isinstance(output, dict) and field in output:
+                    self.available_data[field] = output[field]
+
+    def get_output_data(self) -> dict[str, Any]:
+        """Extract output field values.
+
+        Returns:
+            Dict mapping output field names to values
+        """
+        result = {}
+        for field in self.output_fields:
+            if field in self.available_data:
+                result[field] = self.available_data[field]
+        return result
+
+    async def execute(self, ctx: Any = None) -> Any:
+        """Execute the form if it has a bound phrase.
+
+        Args:
+            ctx: Execution context
+
+        Returns:
+            Execution result
+
+        Raises:
+            RuntimeError: If no phrase bound or form not workable
+        """
+        if self._phrase is None:
+            raise RuntimeError("Form has no bound phrase - cannot execute")
+
+        if not self.is_workable():
+            missing = [f for f in self.input_fields if f not in self.available_data]
+            raise RuntimeError(f"Form not workable - missing inputs: {missing}")
+
+        result = await self._phrase(self.get_inputs(), ctx)
+        self.set_output(result)
+        return result
+
+    def __repr__(self) -> str:
+        status = (
+            "filled" if self.filled else ("ready" if self.is_workable() else "pending")
+        )
+        phrase_info = f", phrase={self._phrase.name}" if self._phrase else ""
+        return f"Form('{self.assignment}', {status}{phrase_info})"

krons/{operations → work/operations}/__init__.py

@@ -5,7 +5,7 @@
 
 Core types:
     Operation: Node + Event hybrid for graph-based execution.
-    OperationRegistry: Per-session factory mapping.
+    OperationRegistry: Per-session handler mapping.
     OperationGraphBuilder (Builder): Fluent DAG construction.
 
 Execution:
@@ -16,17 +16,20 @@ Execution:
 from __future__ import annotations
 
 from .builder import Builder, OperationGraphBuilder
+from .context import QueryFn, RequestContext
 from .flow import DependencyAwareExecutor, flow, flow_stream
-from .node import Operation, create_operation
-from .registry import OperationRegistry
+from .node import Operation
+from .registry import OperationHandler, OperationRegistry
 
 __all__ = (
     "Builder",
     "DependencyAwareExecutor",
     "Operation",
     "OperationGraphBuilder",
+    "OperationHandler",
     "OperationRegistry",
-    "create_operation",
+    "QueryFn",
+    "RequestContext",
     "flow",
     "flow_stream",
 )

krons/{operations → work/operations}/builder.py

@@ -13,7 +13,7 @@ from typing import TYPE_CHECKING, Any
 from uuid import UUID
 
 from krons.core import Edge, Graph
-from krons.types import Undefined, UndefinedType, is_sentinel, not_sentinel
+from krons.core.types import Undefined, UndefinedType, is_sentinel, not_sentinel
 from krons.utils._utils import to_uuid
 
 from .node import Operation

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

@@ -11,8 +11,8 @@ from datetime import datetime
 from typing import TYPE_CHECKING, Any, Protocol
 from uuid import UUID, uuid4
 
-from krons.types.base import DataClass
-from krons.types.identity import ID
+from krons.core.types.base import DataClass
+from krons.core.types.identity import ID
 
 if TYPE_CHECKING:
     from krons.session import Branch, Session
@@ -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)

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

@@ -16,7 +16,7 @@ from typing import TYPE_CHECKING, Any
 from uuid import UUID
 
 from krons.core import EventStatus, Graph
-from krons.types import Undefined, UndefinedType, is_sentinel
+from krons.core.types import Undefined, UndefinedType, is_sentinel
 from krons.utils import concurrency
 from krons.utils.concurrency import CapacityLimiter, CompletionStream
 
@@ -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/{operations → work/operations}/node.py

@@ -1,5 +1,13 @@
 # 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
@@ -7,23 +15,36 @@ from typing import TYPE_CHECKING, Any
 from pydantic import Field, PrivateAttr
 
 from krons.core import Event, Node
-from krons.types import Undefined, UndefinedType, is_sentinel
+
+from .context import RequestContext
 
 if TYPE_CHECKING:
     from krons.session import Branch, Session
 
-__all__ = ("Operation", "create_operation")
+__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 (dict or Pydantic model)",
+        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.
@@ -31,11 +52,11 @@ class Operation(Node, Event):
         Must be called before invoke() if not using Session.conduct().
 
         Args:
-            session: Session with operations registry and services
-            branch: Branch for message context
+            session: Session with operations registry and services.
+            branch: Branch for message context.
 
         Returns:
-            Self for chaining
+            Self for chaining.
         """
         self._session = session
         self._branch = branch
@@ -51,51 +72,32 @@ class Operation(Node, Event):
         return self._session, self._branch
 
     async def _invoke(self) -> Any:
-        """Execute via session's operation registry. Called by Event.invoke().
+        """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:
-            Factory result (stored in execution.response).
+            Handler result (stored in execution.response).
 
         Raises:
             RuntimeError: If not bound.
             KeyError: If operation_type not registered.
         """
         session, branch = self._require_binding()
-        factory = session.operations.get(self.operation_type)
-        return await factory(session, branch, self.parameters)
-
-    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})"
+        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 create_operation(
-    operation_type: str | UndefinedType = Undefined,
-    parameters: dict[str, Any] | UndefinedType = Undefined,
-    **kwargs,
-) -> Operation:
-    """Factory for Operation nodes.
-
-    Args:
-        operation_type: Registry key (required).
-        parameters: Factory arguments dict (default: {}).
-        **kwargs: Additional fields (metadata, timeout, etc.).
-
-    Returns:
-        Unbound Operation ready for bind() and invoke().
-
-    Raises:
-        ValueError: If operation_type not provided.
-    """
-    if is_sentinel(operation_type):
-        raise ValueError("operation_type is required")
-
-    resolved_params: dict[str, Any] = {} if is_sentinel(parameters) else parameters
-
-    return Operation(
-        operation_type=operation_type,
-        parameters=resolved_params,
-        **kwargs,
-    )
+    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})"