ddeutil-workflow 0.0.81__py3-none-any.whl → 0.0.83__py3-none-any.whl

ddeutil/workflow/stages.py

@@ -36,16 +36,6 @@ the stage execution method.
 execute method receives a `params={"params": {...}}` value for passing template
 searching.
 
-    All stages model inherit from `BaseStage` or `AsyncBaseStage` models that has the
-base fields:
-
-| field     | alias | data type   | default  | description                                                           |
-|-----------|-------|-------------|:--------:|-----------------------------------------------------------------------|
-| id        |       | str \| None |  `None`  | A stage ID that use to keep execution output or getting by job owner. |
-| name      |       | str         |          | A stage name that want to log when start execution.               |
-| condition | if    | str \| None |  `None`  | A stage condition statement to allow stage executable.                |
-| extras    |       | dict        | `dict()` | An extra parameter that override core config values.                  |
-
     It has a special base class is `BaseRetryStage` that inherit from `AsyncBaseStage`
 that use to handle retry execution when it got any error with `retry` field.
 """
@@ -81,7 +71,9 @@ from typing import (
     Annotated,
     Any,
     Callable,
+    ClassVar,
     Optional,
+    TypedDict,
     TypeVar,
     Union,
     get_type_hints,
@@ -90,11 +82,20 @@ from typing import (
 from ddeutil.core import str2list
 from pydantic import BaseModel, Field, ValidationError
 from pydantic.functional_validators import field_validator, model_validator
-from typing_extensions import Self
+from typing_extensions import NotRequired, Self
 
-from .__types import DictData, DictStr, StrOrInt, StrOrNone, TupleStr
+from .__about__ import __python_version__
+from .__types import DictData, DictStr, StrOrInt, StrOrNone, TupleStr, cast_dict
 from .conf import dynamic, pass_env
-from .errors import StageCancelError, StageError, StageSkipError, to_dict
+from .errors import (
+    StageCancelError,
+    StageError,
+    StageNestedCancelError,
+    StageNestedError,
+    StageNestedSkipError,
+    StageSkipError,
+    to_dict,
+)
 from .result import (
     CANCEL,
     FAILED,
@@ -114,10 +115,11 @@ from .reusables import (
     not_in_template,
     param2template,
 )
-from .traces import TraceManager, get_trace
+from .traces import Trace, get_trace
 from .utils import (
     delay,
     dump_all,
+    extract_id,
     filter_func,
     gen_id,
     make_exec,
@@ -155,16 +157,15 @@ class BaseStage(BaseModel, ABC):
         process: Main execution logic that must be implemented by subclasses
 
     Example:
-        ```python
-        class CustomStage(BaseStage):
-            custom_param: str = Field(description="Custom parameter")
-
-            def process(self, params: dict, **kwargs) -> Result:
-                # Custom execution logic
-                return Result(status=SUCCESS)
+        >>> class CustomStage(BaseStage):
+        ...     custom_param: str = Field(description="Custom parameter")
+        ...
+        ...     def process(self, params: DictData, **kwargs) -> Result:
+        ...         return Result(status=SUCCESS)
         ```
     """
 
+    action_stage: ClassVar[bool] = False
     extras: DictData = Field(
         default_factory=dict,
         description="An extra parameter that override core config values.",
@@ -208,7 +209,8 @@ class BaseStage(BaseModel, ABC):
     def ___prepare_desc__(cls, value: str) -> str:
         """Prepare description string that was created on a template.
 
-        :rtype: str
+        Returns:
+            str: A dedent and left strip newline of description string.
         """
         return dedent(value.lstrip("\n"))
 
@@ -218,19 +220,33 @@ class BaseStage(BaseModel, ABC):
         method will validate name and id fields should not contain any template
         parameter (exclude matrix template).
 
-        :raise ValueError: When the ID and name fields include matrix parameter
-            template with the 'matrix.' string value.
+        Raises:
+            ValueError: When the ID and name fields include matrix parameter
+                template with the 'matrix.' string value.
 
-        :rtype: Self
+        Returns: Self
         """
         # VALIDATE: Validate stage id and name should not dynamic with params
         #   template. (allow only matrix)
         if not_in_template(self.id) or not_in_template(self.name):
             raise ValueError(
-                "Stage name and ID should only template with 'matrix.'"
+                "Stage name and ID should only template with 'matrix.?'."
             )
         return self
 
+    def pass_template(self, value: Any, params: DictData) -> Any:
+        """Pass template and environment variable to any value that can
+        templating.
+
+        Args:
+            value (Any): An any value.
+            params (DictData):
+
+        Returns:
+            Any: A templated value.
+        """
+        return pass_env(param2template(value, params, extras=self.extras))
+
     @abstractmethod
     def process(
         self,
@@ -245,10 +261,10 @@ class BaseStage(BaseModel, ABC):
         This is important method that make this class is able to be the stage.
 
         Args:
-            params: A parameter data that want to use in this
+            params (DictData): A parameter data that want to use in this
                 execution.
-            run_id: A running stage ID.
-            context: A context data.
+            run_id (str): A running stage ID.
+            context (DictData): A context data.
             parent_run_id: A parent running ID. (Default is None)
             event: An event manager that use to track parent process
                 was not force stopped.
@@ -301,10 +317,11 @@ class BaseStage(BaseModel, ABC):
             Result: The execution result with updated status and context.
         """
         ts: float = time.monotonic()
-        parent_run_id: str = run_id
-        run_id: str = run_id or gen_id(self.iden, unique=True)
+        parent_run_id, run_id = extract_id(
+            self.iden, run_id=run_id, extras=self.extras
+        )
         context: DictData = {"status": WAIT}
-        trace: TraceManager = get_trace(
+        trace: Trace = get_trace(
             run_id, parent_run_id=parent_run_id, extras=self.extras
         )
         try:
@@ -349,13 +366,18 @@ class BaseStage(BaseModel, ABC):
         #   this exception class at other location.
         except (
             StageSkipError,
-            StageCancelError,
+            StageNestedSkipError,
+            StageNestedError,
             StageError,
         ) as e:  # pragma: no cov
-            trace.info(
-                f"[STAGE]: Handler:||{e.__class__.__name__}: {e}||"
-                f"{traceback.format_exc()}"
-            )
+            if isinstance(e, StageNestedError):
+                trace.info(f"[STAGE]: Nested: {e}")
+            elif isinstance(e, (StageSkipError, StageNestedSkipError)):
+                trace.info(f"[STAGE]: ⏭️ Skip: {e}")
+            else:
+                trace.info(
+                    f"[STAGE]: Stage Failed:||🚨 {traceback.format_exc()}||"
+                )
             st: Status = get_status_from_error(e)
             return Result(
                 run_id=run_id,
@@ -366,7 +388,7 @@ class BaseStage(BaseModel, ABC):
                     status=st,
                     updated=(
                         None
-                        if isinstance(e, StageSkipError)
+                        if isinstance(e, (StageSkipError, StageNestedSkipError))
                         else {"errors": e.to_dict()}
                     ),
                 ),
@@ -375,8 +397,7 @@ class BaseStage(BaseModel, ABC):
             )
         except Exception as e:
             trace.error(
-                f"[STAGE]: Error Handler:||{e.__class__.__name__}: {e}||"
-                f"{traceback.format_exc()}"
+                f"[STAGE]: Error Failed:||🚨 {traceback.format_exc()}||"
             )
             return Result(
                 run_id=run_id,
@@ -488,10 +509,12 @@ class BaseStage(BaseModel, ABC):
         """Get the outputs from stages data. It will get this stage ID from
         the stage outputs mapping.
 
-        :param output: (DictData) A stage output context that want to get this
-            stage ID `outputs` key.
+        Args:
+            output (DictData): A stage output context that want to get this
+                stage ID `outputs` key.
 
-        :rtype: DictData
+        Returns:
+            DictData: An output value that have get with its identity.
         """
         if self.id is None and not dynamic(
             "stage_default_id", extras=self.extras
@@ -564,13 +587,53 @@ class BaseStage(BaseModel, ABC):
         """
         return False
 
-    def docs(self) -> str:  # pragma: no cov
+    def detail(self) -> DictData:  # pragma: no cov
+        """Return the detail of this stage for generate markdown.
+
+        Returns:
+            DictData: A dict that was dumped from this model with alias mode.
+        """
+        return self.model_dump(by_alias=True)
+
+    def md(self) -> str:  # pragma: no cov
         """Return generated document that will be the interface of this stage.
 
         :rtype: str
         """
         return self.desc
 
+    def dryrun(
+        self,
+        params: DictData,
+        run_id: str,
+        context: DictData,
+        *,
+        parent_run_id: Optional[str] = None,
+        event: Optional[Event] = None,
+    ) -> Optional[Result]:  # pragma: no cov
+        """Pre-process method that will use to run with dry-run mode, and it
+        should be used before process method.
+        """
+
+    def to_empty(self, sleep: int = 0.35) -> EmptyStage:  # pragma: no cov
+        """Convert the current Stage model to the EmptyStage model for dry-run
+        mode if the `action_stage` class attribute has set.
+
+        Returns:
+            EmptyStage: An EmptyStage model that passing itself model data to
+                message.
+        """
+        return EmptyStage.model_validate(
+            {
+                "name": self.name,
+                "id": self.id,
+                "desc": self.desc,
+                "if": self.condition,
+                "echo": f"Convert from {self.__class__.__name__}",
+                "sleep": sleep,
+            }
+        )
+
 
 class BaseAsyncStage(BaseStage, ABC):
     """Base Async Stage model to make any stage model allow async execution for
@@ -632,9 +695,9 @@ class BaseAsyncStage(BaseStage, ABC):
         """
         ts: float = time.monotonic()
         parent_run_id: StrOrNone = run_id
-        run_id: str = run_id or gen_id(self.iden, unique=True)
+        run_id: str = gen_id(self.iden, unique=True, extras=self.extras)
         context: DictData = {}
-        trace: TraceManager = get_trace(
+        trace: Trace = get_trace(
             run_id, parent_run_id=parent_run_id, extras=self.extras
         )
         try:
@@ -677,13 +740,18 @@ class BaseAsyncStage(BaseStage, ABC):
         #   this exception class at other location.
         except (
             StageSkipError,
-            StageCancelError,
+            StageNestedSkipError,
+            StageNestedError,
             StageError,
         ) as e:  # pragma: no cov
-            await trace.ainfo(
-                f"[STAGE]: Skip Handler:||{e.__class__.__name__}: {e}||"
-                f"{traceback.format_exc()}"
-            )
+            if isinstance(e, StageNestedError):
+                await trace.ainfo(f"[STAGE]: Nested: {e}")
+            elif isinstance(e, (StageSkipError, StageNestedSkipError)):
+                await trace.ainfo(f"[STAGE]: ⏭️ Skip: {e}")
+            else:
+                await trace.ainfo(
+                    f"[STAGE]: Stage Failed:||🚨 {traceback.format_exc()}||"
+                )
             st: Status = get_status_from_error(e)
             return Result(
                 run_id=run_id,
@@ -694,8 +762,8 @@ class BaseAsyncStage(BaseStage, ABC):
                     status=st,
                     updated=(
                         None
-                        if isinstance(e, StageSkipError)
-                        else {"status": st, "errors": e.to_dict()}
+                        if isinstance(e, (StageSkipError, StageNestedSkipError))
+                        else {"errors": e.to_dict()}
                     ),
                 ),
                 info={"execution_time": time.monotonic() - ts},
@@ -703,8 +771,7 @@ class BaseAsyncStage(BaseStage, ABC):
             )
         except Exception as e:
             await trace.aerror(
-                f"[STAGE]: Error Handler:||{e.__class__.__name__}: {e}||"
-                f"{traceback.format_exc()}"
+                f"[STAGE]: Error Failed:||🚨 {traceback.format_exc()}||"
             )
             return Result(
                 run_id=run_id,
@@ -777,7 +844,7 @@ class BaseRetryStage(BaseAsyncStage, ABC):  # pragma: no cov
         current_retry: int = 0
         exception: Exception
         catch(context, status=WAIT)
-        trace: TraceManager = get_trace(
+        trace: Trace = get_trace(
             run_id, parent_run_id=parent_run_id, extras=self.extras
         )
 
@@ -816,6 +883,14 @@ class BaseRetryStage(BaseAsyncStage, ABC):  # pragma: no cov
                     parent_run_id=parent_run_id,
                     event=event,
                 )
+            except (
+                StageSkipError,
+                StageNestedSkipError,
+                StageCancelError,
+                StageNestedCancelError,
+            ):
+                trace.debug("[STAGE]: process raise skip or cancel error.")
+                raise
             except Exception as e:
                 current_retry += 1
                 trace.warning(
@@ -823,6 +898,7 @@ class BaseRetryStage(BaseAsyncStage, ABC):  # pragma: no cov
                     f"( {e.__class__.__name__} )"
                 )
                 exception = e
+                time.sleep(1.2**current_retry)
 
         trace.error(
             f"[STAGE]: Reach the maximum of retry number: {self.retry}."
@@ -850,7 +926,7 @@ class BaseRetryStage(BaseAsyncStage, ABC):  # pragma: no cov
         current_retry: int = 0
         exception: Exception
         catch(context, status=WAIT)
-        trace: TraceManager = get_trace(
+        trace: Trace = get_trace(
             run_id, parent_run_id=parent_run_id, extras=self.extras
         )
 
@@ -889,6 +965,16 @@ class BaseRetryStage(BaseAsyncStage, ABC):  # pragma: no cov
                     parent_run_id=parent_run_id,
                     event=event,
                 )
+            except (
+                StageSkipError,
+                StageNestedSkipError,
+                StageCancelError,
+                StageNestedCancelError,
+            ):
+                await trace.adebug(
+                    "[STAGE]: process raise skip or cancel error."
+                )
+                raise
             except Exception as e:
                 current_retry += 1
                 await trace.awarning(
@@ -896,6 +982,7 @@ class BaseRetryStage(BaseAsyncStage, ABC):  # pragma: no cov
                     f"( {e.__class__.__name__} )"
                 )
                 exception = e
+                await asyncio.sleep(1.2**current_retry)
 
         await trace.aerror(
             f"[STAGE]: Reach the maximum of retry number: {self.retry}."
@@ -908,19 +995,15 @@ class EmptyStage(BaseAsyncStage):
 
     EmptyStage is a utility stage that performs no actual work but provides
     logging output and optional delays. It's commonly used for:
-    - Debugging workflow execution flow
-    - Adding informational messages to workflows
-    - Creating delays between stages
-    - Testing template parameter resolution
+        - Debugging workflow execution flow
+        - Adding informational messages to workflows
+        - Creating delays between stages
+        - Testing template parameter resolution
 
     The stage outputs the echo message to stdout and can optionally sleep
     for a specified duration, making it useful for workflow timing control
     and debugging scenarios.
 
-    Attributes:
-        echo (str, optional): Message to display during execution
-        sleep (float): Duration to sleep after logging (0-1800 seconds)
-
     Example:
         ```yaml
         stages:
@@ -932,24 +1015,25 @@ class EmptyStage(BaseAsyncStage):
             echo: "Processing file: ${{ params.filename }}"
         ```
 
-        ```python
-        stage = EmptyStage(
-            name="Status Update",
-            echo="Processing completed successfully",
-            sleep=1.0
-        )
-        ```
+        >>> stage = EmptyStage(
+        ...     name="Status Update",
+        ...     echo="Processing completed successfully",
+        ...     sleep=1.0
+        ... )
     """
 
     echo: StrOrNone = Field(
         default=None,
-        description="A message that want to show on the stdout.",
+        description=(
+            "A message that want to display on the stdout during execution. "
+            "By default, it do not show any message."
+        ),
     )
     sleep: float = Field(
         default=0,
         description=(
-            "A second value to sleep before start execution. This value should "
-            "gather or equal 0, and less than 1800 seconds."
+            "A duration in second value to sleep after logging. This value "
+            "should between 0 - 1800 seconds."
         ),
         ge=0,
         lt=1800,
@@ -982,7 +1066,7 @@ class EmptyStage(BaseAsyncStage):
         Returns:
             Result: The execution result with status and context data.
         """
-        trace: TraceManager = get_trace(
+        trace: Trace = get_trace(
             run_id, parent_run_id=parent_run_id, extras=self.extras
         )
         message: str = (
@@ -994,9 +1078,7 @@ class EmptyStage(BaseAsyncStage):
         )
 
         if event and event.is_set():
-            raise StageCancelError(
-                "Execution was canceled from the event before start parallel."
-            )
+            raise StageCancelError("Cancel before start empty process.")
 
         trace.info(f"[STAGE]: Message: ( {message} )")
         if self.sleep > 0:
@@ -1035,7 +1117,7 @@ class EmptyStage(BaseAsyncStage):
         Returns:
             Result: The execution result with status and context data.
         """
-        trace: TraceManager = get_trace(
+        trace: Trace = get_trace(
             run_id, parent_run_id=parent_run_id, extras=self.extras
         )
         message: str = (
@@ -1047,9 +1129,7 @@ class EmptyStage(BaseAsyncStage):
         )
 
         if event and event.is_set():
-            raise StageCancelError(
-                "Execution was canceled from the event before start parallel."
-            )
+            raise StageCancelError("Cancel before start empty process.")
 
         trace.info(f"[STAGE]: Message: ( {message} )")
         if self.sleep > 0:
@@ -1200,7 +1280,7 @@ class BashStage(BaseRetryStage):
         Returns:
             Result: The execution result with status and context data.
         """
-        trace: TraceManager = get_trace(
+        trace: Trace = get_trace(
             run_id, parent_run_id=parent_run_id, extras=self.extras
         )
         bash: str = param2template(
@@ -1264,7 +1344,7 @@ class BashStage(BaseRetryStage):
         Returns:
             Result: The execution result with status and context data.
         """
-        trace: TraceManager = get_trace(
+        trace: Trace = get_trace(
             run_id, parent_run_id=parent_run_id, extras=self.extras
         )
         bash: str = param2template(
@@ -1394,21 +1474,21 @@ class PyStage(BaseRetryStage):
         to globals argument on `exec` build-in function.
 
         Args:
-            params: A parameter data that want to use in this
+            params (DictData): A parameter data that want to use in this
                 execution.
-            run_id: A running stage ID.
+            run_id (str): A running stage ID.
             context: A context data.
-            parent_run_id: A parent running ID. (Default is None)
+            parent_run_id (str | None, default None): A parent running ID.
             event: An event manager that use to track parent process
                 was not force stopped.
 
         Returns:
             Result: The execution result with status and context data.
         """
-        trace: TraceManager = get_trace(
+        trace: Trace = get_trace(
             run_id, parent_run_id=parent_run_id, extras=self.extras
         )
-        trace.info("[STAGE]: Prepare `globals` and `locals` variables.")
+        trace.debug("[STAGE]: Prepare `globals` and `locals` variables.")
         lc: DictData = {}
         gb: DictData = (
             globals()
@@ -1486,7 +1566,7 @@ class PyStage(BaseRetryStage):
         Returns:
             Result: The execution result with status and context data.
         """
-        trace: TraceManager = get_trace(
+        trace: Trace = get_trace(
             run_id, parent_run_id=parent_run_id, extras=self.extras
         )
         await trace.ainfo("[STAGE]: Prepare `globals` and `locals` variables.")
@@ -1631,7 +1711,7 @@ class CallStage(BaseRetryStage):
         Returns:
             Result: The execution result with status and context data.
         """
-        trace: TraceManager = get_trace(
+        trace: Trace = get_trace(
             run_id, parent_run_id=parent_run_id, extras=self.extras
         )
         call_func: TagFunc = self.get_caller(params=params)()
@@ -1687,9 +1767,7 @@ class CallStage(BaseRetryStage):
             args.pop("extras")
 
         if event and event.is_set():
-            raise StageCancelError(
-                "Execution was canceled from the event before start parallel."
-            )
+            raise StageCancelError("Cancel before start call process.")
 
         args: DictData = self.validate_model_args(
             call_func, args, run_id, parent_run_id, extras=self.extras
@@ -1750,7 +1828,7 @@ class CallStage(BaseRetryStage):
         Returns:
             Result: The execution result with status and context data.
         """
-        trace: TraceManager = get_trace(
+        trace: Trace = get_trace(
             run_id, parent_run_id=parent_run_id, extras=self.extras
         )
         call_func: TagFunc = self.get_caller(params=params)()
@@ -1807,9 +1885,7 @@ class CallStage(BaseRetryStage):
             args.pop("extras")
 
         if event and event.is_set():
-            raise StageCancelError(
-                "Execution was canceled from the event before start parallel."
-            )
+            raise StageCancelError("Cancel before start call process.")
 
         args: DictData = self.validate_model_args(
             call_func, args, run_id, parent_run_id, extras=self.extras
@@ -1884,7 +1960,7 @@ class CallStage(BaseRetryStage):
                 "Validate argument from the caller function raise invalid type."
             ) from e
         except TypeError as e:
-            trace: TraceManager = get_trace(
+            trace: Trace = get_trace(
                 run_id, parent_run_id=parent_run_id, extras=extras
             )
             trace.warning(
@@ -1922,8 +1998,9 @@ class BaseNestedStage(BaseRetryStage, ABC):
         """Make the errors context result with the refs value depends on the nested
         execute func.
 
-        :param context: (DictData) A context data.
-        :param error: (StageError) A stage exception object.
+        Args:
+            context: (DictData) A context data.
+            error: (StageError) A stage exception object.
         """
         if "errors" in context:
             context["errors"][error.refs] = error.to_dict()
@@ -1963,6 +2040,9 @@ class TriggerStage(BaseNestedStage):
     execute method. This is the stage that allow you to create the reusable
     Workflow template with dynamic parameters.
 
+        This stage does not allow to pass the workflow model directly to the
+    trigger field. A trigger workflow name should exist on the config path only.
+
     Data Validate:
         >>> stage = {
         ...     "name": "Trigger workflow stage execution",
@@ -2009,11 +2089,13 @@ class TriggerStage(BaseNestedStage):
         """
         from .workflow import Workflow
 
-        trace: TraceManager = get_trace(
+        trace: Trace = get_trace(
             run_id, parent_run_id=parent_run_id, extras=self.extras
         )
         _trigger: str = param2template(self.trigger, params, extras=self.extras)
-        trace.info(f"[STAGE]: Load workflow: {_trigger!r}")
+        if _trigger == self.extras.get("__sys_break_circle_exec", "NOTSET"):
+            raise StageError("Circle execute via trigger itself workflow name.")
+        trace.info(f"[NESTED]: Load Workflow Config: {_trigger!r}")
         result: Result = Workflow.from_conf(
             name=pass_env(_trigger),
             extras=self.extras,
@@ -2024,19 +2106,48 @@ class TriggerStage(BaseNestedStage):
             event=event,
         )
         if result.status == FAILED:
-            err_msg: StrOrNone = (
+            err_msg: str = (
                 f" with:\n{msg}"
                 if (msg := result.context.get("errors", {}).get("message"))
                 else "."
             )
-            raise StageError(f"Trigger workflow was failed{err_msg}")
+            return result.catch(
+                status=FAILED,
+                context={
+                    "status": FAILED,
+                    "errors": StageError(
+                        f"Trigger workflow was failed{err_msg}"
+                    ).to_dict(),
+                },
+            )
         elif result.status == CANCEL:
-            raise StageCancelError("Trigger workflow was cancel.")
+            return result.catch(
+                status=CANCEL,
+                context={
+                    "status": CANCEL,
+                    "errors": StageCancelError(
+                        "Trigger workflow was cancel."
+                    ).to_dict(),
+                },
+            )
         elif result.status == SKIP:
-            raise StageSkipError("Trigger workflow was skipped.")
+            return result.catch(
+                status=SKIP,
+                context={
+                    "status": SKIP,
+                    "errors": StageSkipError(
+                        "Trigger workflow was skipped."
+                    ).to_dict(),
+                },
+            )
         return result
 
 
+class ParallelContext(TypedDict):
+    branch: str
+    stages: NotRequired[dict[str, Any]]
+
+
 class ParallelStage(BaseNestedStage):
     """Parallel stage executor that execute branch stages with multithreading.
     This stage let you set the fix branches for running child stage inside it on
@@ -2074,10 +2185,8 @@ class ParallelStage(BaseNestedStage):
     parallel: dict[str, list[Stage]] = Field(
         description="A mapping of branch name and its stages.",
     )
-    max_workers: int = Field(
+    max_workers: Union[int, str] = Field(
         default=2,
-        ge=1,
-        lt=20,
         description=(
             "The maximum multi-thread pool worker size for execution parallel. "
             "This value should be gather or equal than 1, and less than 20."
@@ -2085,44 +2194,47 @@ class ParallelStage(BaseNestedStage):
         alias="max-workers",
     )
 
-    def _process_branch(
+    @field_validator("max_workers")
+    def __validate_max_workers(cls, value: Union[int, str]) -> Union[int, str]:
+        """Validate `max_workers` field that should has value between 1 and 19."""
+        if isinstance(value, int) and (value < 1 or value >= 20):
+            raise ValueError("A max-workers value should between 1 and 19.")
+        return value
+
+    def _process_nested(
         self,
         branch: str,
         params: DictData,
-        run_id: str,
+        trace: Trace,
         context: DictData,
         *,
-        parent_run_id: Optional[str] = None,
         event: Optional[Event] = None,
     ) -> tuple[Status, DictData]:
         """Execute branch that will execute all nested-stage that was set in
         this stage with specific branch ID.
 
-        :param branch: (str) A branch ID.
-        :param params: (DictData) A parameter data.
-        :param run_id: (str)
-        :param context: (DictData)
-        :param parent_run_id: (str | None)
-        :param event: (Event) An Event manager instance that use to cancel this
-            execution if it forces stopped by parent execution.
-            (Default is None)
+        Args:
+            branch (str): A branch ID.
+            params (DictData): A parameter data.
+            trace (Trace): A Trace model.
+            context (DictData):
+            event: (Event) An Event manager instance that use to cancel this
+                execution if it forces stopped by parent execution.
+                (Default is None)
 
-        :raise StageCancelError: If event was set.
-        :raise StageCancelError: If result from a nested-stage return canceled
-            status.
-        :raise StageError: If result from a nested-stage return failed status.
+        Raises:
+            StageCancelError: If event was set before start stage execution.
+            StageCancelError: If result from a nested-stage return canceled
+                status.
+            StageError: If result from a nested-stage return failed status.
 
-        :rtype: tuple[Status, DictData]
+        Returns:
+            tuple[Status, DictData]: A pair of status and result context data.
         """
-        trace: TraceManager = get_trace(
-            run_id, parent_run_id=parent_run_id, extras=self.extras
-        )
-        trace.debug(f"[STAGE]: Execute Branch: {branch!r}")
-
-        # NOTE: Create nested-context
+        trace.info(f"[NESTED]: Execute Branch: {branch!r}")
         current_context: DictData = copy.deepcopy(params)
         current_context.update({"branch": branch})
-        nestet_context: DictData = {"branch": branch, "stages": {}}
+        nestet_context: ParallelContext = {"branch": branch, "stages": {}}
 
         total_stage: int = len(self.parallel[branch])
         skips: list[bool] = [False] * total_stage
@@ -2133,8 +2245,7 @@ class ParallelStage(BaseNestedStage):
 
             if event and event.is_set():
                 error_msg: str = (
-                    "Branch execution was canceled from the event before "
-                    "start branch execution."
+                    f"Cancel branch: {branch!r} before start nested process."
                 )
                 catch(
                     context=context,
@@ -2154,12 +2265,12 @@ class ParallelStage(BaseNestedStage):
 
             rs: Result = stage.execute(
                 params=current_context,
-                run_id=parent_run_id,
+                run_id=trace.parent_run_id,
                 event=event,
             )
-            stage.set_outputs(rs.context, to=nestet_context)
+            stage.set_outputs(rs.context, to=cast_dict(nestet_context))
             stage.set_outputs(
-                stage.get_outputs(nestet_context), to=current_context
+                stage.get_outputs(cast_dict(nestet_context)), to=current_context
             )
 
             if rs.status == SKIP:
@@ -2168,7 +2279,7 @@ class ParallelStage(BaseNestedStage):
 
             elif rs.status == FAILED:  # pragma: no cov
                 error_msg: str = (
-                    f"Branch execution was break because its nested-stage, "
+                    f"Break branch: {branch!r} because nested stage: "
                     f"{stage.iden!r}, failed."
                 )
                 catch(
@@ -2189,8 +2300,7 @@ class ParallelStage(BaseNestedStage):
 
             elif rs.status == CANCEL:
                 error_msg: str = (
-                    "Branch execution was canceled from the event after "
-                    "end branch execution."
+                    f"Cancel branch: {branch!r} after end nested process."
                 )
                 catch(
                     context=context,
@@ -2230,7 +2340,9 @@ class ParallelStage(BaseNestedStage):
         parent_run_id: Optional[str] = None,
         event: Optional[Event] = None,
     ) -> Result:
-        """Execute parallel each branch via multi-threading pool.
+        """Execute parallel each branch via multi-threading pool. The parallel
+        process will use all-completed strategy to handle result from each
+        branch.
 
         Args:
             params: A parameter data that want to use in this
@@ -2241,34 +2353,46 @@ class ParallelStage(BaseNestedStage):
             event: An event manager that use to track parent process
                 was not force stopped.
 
+        Raises:
+            StageCancelError: If event was set before start parallel process.
+
         Returns:
             Result: The execution result with status and context data.
         """
-        trace: TraceManager = get_trace(
+        trace: Trace = get_trace(
             run_id, parent_run_id=parent_run_id, extras=self.extras
         )
         event: Event = event or Event()
-        trace.info(f"[STAGE]: Parallel with {self.max_workers} workers.")
+
+        # NOTE: Start prepare max_workers field if it is string type.
+        if isinstance(self.max_workers, str):
+            max_workers: int = self.__validate_max_workers(
+                pass_env(
+                    param2template(
+                        self.max_workers, params=params, extras=self.extras
+                    )
+                )
+            )
+        else:
+            max_workers: int = self.max_workers
+        trace.info(f"[NESTED]: Parallel with {max_workers} workers.")
         catch(
             context=context,
             status=WAIT,
-            updated={"workers": self.max_workers, "parallel": {}},
+            updated={"workers": max_workers, "parallel": {}},
         )
         len_parallel: int = len(self.parallel)
         if event and event.is_set():
-            raise StageCancelError(
-                "Execution was canceled from the event before start parallel."
-            )
+            raise StageCancelError("Cancel before start parallel process.")
 
-        with ThreadPoolExecutor(self.max_workers, "stp") as executor:
+        with ThreadPoolExecutor(max_workers, "stp") as executor:
             futures: list[Future] = [
                 executor.submit(
-                    self._process_branch,
+                    self._process_nested,
                     branch=branch,
                     params=params,
-                    run_id=run_id,
+                    trace=trace,
                     context=context,
-                    parent_run_id=parent_run_id,
                     event=event,
                 )
                 for branch in self.parallel
@@ -2283,15 +2407,21 @@ class ParallelStage(BaseNestedStage):
                     self.mark_errors(errors, e)
 
         st: Status = validate_statuses(statuses)
-        return Result(
-            run_id=run_id,
-            parent_run_id=parent_run_id,
+        return Result.from_trace(trace).catch(
             status=st,
             context=catch(context, status=st, updated=errors),
-            extras=self.extras,
         )
 
 
+EachType = Union[
+    list[str],
+    list[int],
+    str,
+    dict[str, Any],
+    dict[int, Any],
+]
+
+
 class ForEachStage(BaseNestedStage):
     """For-Each stage executor that execute all stages with each item in the
     foreach list.
@@ -2312,13 +2442,7 @@ class ForEachStage(BaseNestedStage):
         ... }
     """
 
-    foreach: Union[
-        list[str],
-        list[int],
-        str,
-        dict[str, Any],
-        dict[int, Any],
-    ] = Field(
+    foreach: EachType = Field(
         description=(
             "A items for passing to stages via ${{ item }} template parameter."
         ),
@@ -2347,15 +2471,14 @@ class ForEachStage(BaseNestedStage):
         ),
     )
 
-    def _process_item(
+    def _process_nested(
         self,
         index: int,
         item: StrOrInt,
         params: DictData,
-        run_id: str,
+        trace: Trace,
         context: DictData,
         *,
-        parent_run_id: Optional[str] = None,
         event: Optional[Event] = None,
     ) -> tuple[Status, DictData]:
         """Execute item that will execute all nested-stage that was set in this
@@ -2364,32 +2487,29 @@ class ForEachStage(BaseNestedStage):
             This method will create the nested-context from an input context
         data and use it instead the context data.
 
-        :param index: (int) An index value of foreach loop.
-        :param item: (str | int) An item that want to execution.
-        :param params: (DictData) A parameter data.
-        :param run_id: (str)
-        :param context: (DictData)
-        :param parent_run_id: (str | None)
-        :param event: (Event) An Event manager instance that use to cancel this
-            execution if it forces stopped by parent execution.
-            (Default is None)
+        Args:
+            index: (int) An index value of foreach loop.
+            item: (str | int) An item that want to execution.
+            params: (DictData) A parameter data.
+            trace (Trace): A Trace model.
+            context: (DictData)
+            event: (Event) An Event manager instance that use to cancel this
+                execution if it forces stopped by parent execution.
+                (Default is None)
 
             This method should raise error when it wants to stop the foreach
         loop such as cancel event or getting the failed status.
 
-        :raise StageCancelError: If event was set.
-        :raise StageError: If the stage execution raise any Exception error.
-        :raise StageError: If the result from execution has `FAILED` status.
+        Raises:
+            StageCancelError: If event was set.
+            StageError: If the stage execution raise any Exception error.
+            StageError: If the result from execution has `FAILED` status.
 
-        :rtype: tuple[Status, Result]
+        Returns:
+            tuple[Status, DictData]
         """
-        trace: TraceManager = get_trace(
-            run_id, parent_run_id=parent_run_id, extras=self.extras
-        )
-        trace.debug(f"[STAGE]: Execute Item: {item!r}")
+        trace.info(f"[NESTED]: Execute Item: {item!r}")
         key: StrOrInt = index if self.use_index_as_key else item
-
-        # NOTE: Create nested-context data from the passing context.
         current_context: DictData = copy.deepcopy(params)
         current_context.update({"item": item, "loop": index})
         nestet_context: DictData = {"item": item, "stages": {}}
@@ -2403,8 +2523,7 @@ class ForEachStage(BaseNestedStage):
 
             if event and event.is_set():
                 error_msg: str = (
-                    "Item execution was canceled from the event before start "
-                    "item execution."
+                    f"Cancel item: {key!r} before start nested process."
                 )
                 catch(
                     context=context,
@@ -2422,10 +2541,9 @@ class ForEachStage(BaseNestedStage):
                 )
                 raise StageCancelError(error_msg, refs=key)
 
-            # NOTE: Nested-stage execute will pass only params and context only.
             rs: Result = stage.execute(
                 params=current_context,
-                run_id=parent_run_id,
+                run_id=trace.parent_run_id,
                 event=event,
             )
             stage.set_outputs(rs.context, to=nestet_context)
@@ -2439,10 +2557,10 @@ class ForEachStage(BaseNestedStage):
 
             elif rs.status == FAILED:  # pragma: no cov
                 error_msg: str = (
-                    f"Item execution was break because its nested-stage, "
+                    f"Break item: {key!r} because nested stage: "
                     f"{stage.iden!r}, failed."
                 )
-                trace.warning(f"[STAGE]: {error_msg}")
+                trace.warning(f"[NESTED]: {error_msg}")
                 catch(
                     context=context,
                     status=FAILED,
@@ -2461,8 +2579,7 @@ class ForEachStage(BaseNestedStage):
 
             elif rs.status == CANCEL:
                 error_msg: str = (
-                    "Item execution was canceled from the event after "
-                    "end item execution."
+                    f"Cancel item: {key!r} after end nested process."
                 )
                 catch(
                     context=context,
@@ -2493,6 +2610,42 @@ class ForEachStage(BaseNestedStage):
             },
         )
 
+    def validate_foreach(self, value: Any) -> list[Any]:
+        """Validate foreach value that already passed to this model.
+
+        Args:
+            value:
+
+        Raises:
+            TypeError: If value can not try-convert to list type.
+            ValueError:
+
+        Returns:
+            list[Any]: list of item.
+        """
+        if isinstance(value, str):
+            try:
+                value: list[Any] = str2list(value)
+            except ValueError as e:
+                raise TypeError(
+                    f"Does not support string foreach: {value!r} that can "
+                    f"not convert to list."
+                ) from e
+        # [VALIDATE]: Type of the foreach should be `list` type.
+        elif isinstance(value, dict):
+            raise TypeError(
+                f"Does not support dict foreach: {value!r} ({type(value)}) "
+                f"yet."
+            )
+        # [Validate]: Value in the foreach item should not be duplicate when the
+        #   `use_index_as_key` field did not set.
+        elif len(set(value)) != len(value) and not self.use_index_as_key:
+            raise ValueError(
+                "Foreach item should not duplicate. If this stage must to pass "
+                "duplicate item, it should set `use_index_as_key: true`."
+            )
+        return value
+
     def process(
         self,
         params: DictData,
@@ -2520,39 +2673,13 @@ class ForEachStage(BaseNestedStage):
         Returns:
             Result: The execution result with status and context data.
         """
-        trace: TraceManager = get_trace(
+        trace: Trace = get_trace(
             run_id, parent_run_id=parent_run_id, extras=self.extras
         )
         event: Event = event or Event()
-        foreach: Union[list[str], list[int], str] = pass_env(
-            param2template(self.foreach, params, extras=self.extras)
-        )
-
-        # [NOTE]: Force convert str to list.
-        if isinstance(foreach, str):
-            try:
-                foreach: list[Any] = str2list(foreach)
-            except ValueError as e:
-                raise TypeError(
-                    f"Does not support string foreach: {foreach!r} that can "
-                    f"not convert to list."
-                ) from e
-
-        # [VALIDATE]: Type of the foreach should be `list` type.
-        elif isinstance(foreach, dict):
-            raise TypeError(
-                f"Does not support dict foreach: {foreach!r} ({type(foreach)}) "
-                f"yet."
-            )
-        # [Validate]: Value in the foreach item should not be duplicate when the
-        #   `use_index_as_key` field did not set.
-        elif len(set(foreach)) != len(foreach) and not self.use_index_as_key:
-            raise ValueError(
-                "Foreach item should not duplicate. If this stage must to pass "
-                "duplicate item, it should set `use_index_as_key: true`."
-            )
-
-        trace.info(f"[STAGE]: Foreach: {foreach!r}.")
+        foreach: EachType = self.pass_template(self.foreach, params=params)
+        foreach: list[Any] = self.validate_foreach(foreach)
+        trace.info(f"[NESTED]: Foreach: {foreach!r}.")
         catch(
             context=context,
             status=WAIT,
@@ -2560,39 +2687,35 @@ class ForEachStage(BaseNestedStage):
         )
         len_foreach: int = len(foreach)
         if event and event.is_set():
-            raise StageCancelError(
-                "Execution was canceled from the event before start foreach."
-            )
+            raise StageCancelError("Cancel before start foreach process.")
 
         with ThreadPoolExecutor(self.concurrent, "stf") as executor:
             futures: list[Future] = [
                 executor.submit(
-                    self._process_item,
-                    index=i,
+                    self._process_nested,
+                    index=index,
                     item=item,
                     params=params,
-                    run_id=run_id,
+                    trace=trace,
                     context=context,
-                    parent_run_id=parent_run_id,
                     event=event,
                 )
-                for i, item in enumerate(foreach, start=0)
+                for index, item in enumerate(foreach, start=0)
             ]
 
             errors: DictData = {}
             statuses: list[Status] = [WAIT] * len_foreach
-            fail_fast: bool = False
 
             done, not_done = wait(futures, return_when=FIRST_EXCEPTION)
             if len(list(done)) != len(futures):
                 trace.warning(
-                    "[STAGE]: Set the event for stop pending for-each stage."
+                    "[NESTED]: Set the event for stop pending for-each stage."
                 )
                 event.set()
                 for future in not_done:
                     future.cancel()
 
-                time.sleep(0.01)  # Reduced from 0.025 for better responsiveness
+                time.sleep(0.025)
                 nd: str = (
                     (
                         f", {len(not_done)} item"
@@ -2601,9 +2724,8 @@ class ForEachStage(BaseNestedStage):
                     if not_done
                     else ""
                 )
-                trace.debug(f"[STAGE]: ... Foreach-Stage set failed event{nd}")
+                trace.debug(f"[NESTED]: ... Foreach-Stage set failed event{nd}")
                 done: Iterator[Future] = as_completed(futures)
-                fail_fast = True
 
             for i, future in enumerate(done, start=0):
                 try:
@@ -2613,21 +2735,13 @@ class ForEachStage(BaseNestedStage):
                     statuses[i] = get_status_from_error(e)
                     self.mark_errors(errors, e)
                 except CancelledError:
+                    statuses[i] = CANCEL
                     pass
 
         status: Status = validate_statuses(statuses)
-
-        # NOTE: Prepare status because it does not cancel from parent event but
-        #   cancel from failed item execution.
-        if fail_fast and status == CANCEL:
-            status = FAILED
-
-        return Result(
-            run_id=run_id,
-            parent_run_id=parent_run_id,
+        return Result.from_trace(trace).catch(
             status=status,
             context=catch(context, status=status, updated=errors),
-            extras=self.extras,
         )
 
 
@@ -2662,7 +2776,7 @@ class UntilStage(BaseNestedStage):
         ),
     )
     until: str = Field(description="A until condition for stop the while loop.")
-    stages: list[Stage] = Field(
+    stages: list[NestedStage] = Field(
         default_factory=list,
         description=(
             "A list of stage that will run with each item in until loop."
@@ -2679,38 +2793,33 @@ class UntilStage(BaseNestedStage):
         alias="max-loop",
     )
 
-    def _process_loop(
+    def _process_nested(
         self,
         item: T,
         loop: int,
         params: DictData,
-        run_id: str,
+        trace: Trace,
         context: DictData,
         *,
-        parent_run_id: Optional[str] = None,
         event: Optional[Event] = None,
     ) -> tuple[Status, DictData, T]:
         """Execute loop that will execute all nested-stage that was set in this
         stage with specific loop and item.
 
-        :param item: (T) An item that want to execution.
-        :param loop: (int) A number of loop.
-        :param params: (DictData) A parameter data.
-        :param run_id: (str)
-        :param context: (DictData)
-        :param parent_run_id: (str | None)
-        :param event: (Event) An Event manager instance that use to cancel this
-            execution if it forces stopped by parent execution.
+        Args:
+            item: (T) An item that want to execution.
+            loop: (int) A number of loop.
+            params: (DictData) A parameter data.
+            trace: (Trace)
+            context: (DictData)
+            event: (Event) An Event manager instance that use to cancel this
+                execution if it forces stopped by parent execution.
 
-        :rtype: tuple[Status, DictData, T]
-        :return: Return a pair of Result and changed item.
+        Returns:
+            tuple[Status, DictData, T]: Return a pair of Result and changed
+                item.
         """
-        trace: TraceManager = get_trace(
-            run_id, parent_run_id=parent_run_id, extras=self.extras
-        )
-        trace.debug(f"[STAGE]: Execute Loop: {loop} (Item {item!r})")
-
-        # NOTE: Create nested-context
+        trace.debug(f"[NESTED]: Execute Loop: {loop} (Item {item!r})")
         current_context: DictData = copy.deepcopy(params)
         current_context.update({"item": item, "loop": loop})
         nestet_context: DictData = {"loop": loop, "item": item, "stages": {}}
@@ -2725,8 +2834,7 @@ class UntilStage(BaseNestedStage):
 
             if event and event.is_set():
                 error_msg: str = (
-                    "Loop execution was canceled from the event before start "
-                    "loop execution."
+                    f"Cancel loop: {i!r} before start nested process."
                 )
                 catch(
                     context=context,
@@ -2747,7 +2855,7 @@ class UntilStage(BaseNestedStage):
 
             rs: Result = stage.execute(
                 params=current_context,
-                run_id=parent_run_id,
+                run_id=trace.parent_run_id,
                 event=event,
             )
             stage.set_outputs(rs.context, to=nestet_context)
@@ -2763,8 +2871,8 @@ class UntilStage(BaseNestedStage):
 
             elif rs.status == FAILED:
                 error_msg: str = (
-                    f"Loop execution was break because its nested-stage, "
-                    f"{stage.iden!r}, failed."
+                    f"Break loop: {i!r} because nested stage: {stage.iden!r}, "
+                    f"failed."
                 )
                 catch(
                     context=context,
@@ -2777,17 +2885,14 @@ class UntilStage(BaseNestedStage):
                             "stages": filter_func(
                                 nestet_context.pop("stages", {})
                             ),
-                            "errors": StageError(error_msg).to_dict(),
+                            "errors": StageNestedError(error_msg).to_dict(),
                         }
                     },
                 )
-                raise StageError(error_msg, refs=loop)
+                raise StageNestedError(error_msg, refs=loop)
 
             elif rs.status == CANCEL:
-                error_msg: str = (
-                    "Loop execution was canceled from the event after "
-                    "end loop execution."
-                )
+                error_msg: str = f"Cancel loop: {i!r} after end nested process."
                 catch(
                     context=context,
                     status=CANCEL,
@@ -2799,11 +2904,13 @@ class UntilStage(BaseNestedStage):
                             "stages": filter_func(
                                 nestet_context.pop("stages", {})
                             ),
-                            "errors": StageCancelError(error_msg).to_dict(),
+                            "errors": StageNestedCancelError(
+                                error_msg
+                            ).to_dict(),
                         }
                     },
                 )
-                raise StageCancelError(error_msg, refs=loop)
+                raise StageNestedCancelError(error_msg, refs=loop)
 
         status: Status = SKIP if sum(skips) == total_stage else SUCCESS
         return (
@@ -2847,41 +2954,39 @@ class UntilStage(BaseNestedStage):
         Returns:
             Result: The execution result with status and context data.
         """
-        trace: TraceManager = get_trace(
+        trace: Trace = get_trace(
             run_id, parent_run_id=parent_run_id, extras=self.extras
         )
         event: Event = event or Event()
-        trace.info(f"[STAGE]: Until: {self.until!r}")
-        item: Union[str, int, bool] = pass_env(
-            param2template(self.item, params, extras=self.extras)
-        )
+        trace.info(f"[NESTED]: Until: {self.until!r}")
+        item: Union[str, int, bool] = self.pass_template(self.item, params)
         loop: int = 1
         until_rs: bool = True
         exceed_loop: bool = False
         catch(context=context, status=WAIT, updated={"until": {}})
         statuses: list[Status] = []
+
         while until_rs and not (exceed_loop := (loop > self.max_loop)):
 
             if event and event.is_set():
                 raise StageCancelError(
-                    "Execution was canceled from the event before start loop."
+                    f"Cancel before start loop process, (loop: {loop})."
                 )
 
-            status, context, item = self._process_loop(
+            status, context, item = self._process_nested(
                 item=item,
                 loop=loop,
                 params=params,
-                run_id=run_id,
+                trace=trace,
                 context=context,
-                parent_run_id=parent_run_id,
                 event=event,
             )
 
             loop += 1
             if item is None:
                 item: int = loop
-                trace.warning(
-                    f"[STAGE]: Return loop not set the item. It uses loop: "
+                trace.debug(
+                    f"[NESTED]: Return loop not set the item. It uses loop: "
                     f"{loop} by default."
                 )
 
@@ -2931,6 +3036,13 @@ class Match(BaseModel):
     )
 
 
+class Else(BaseModel):
+    other: list[Stage] = Field(
+        description="A list of stage that does not match any case.",
+        alias="else",
+    )
+
+
 class CaseStage(BaseNestedStage):
     """Case stage executor that execute all stages if the condition was matched.
 
@@ -2960,10 +3072,34 @@ class CaseStage(BaseNestedStage):
         ...     ],
         ... }
 
+        >>> stage = {
+        ...     "name": "If stage execution.",
+        ...     "case": "${{ param.test }}",
+        ...     "match": [
+        ...         {
+        ...             "case": "1",
+        ...             "stages": [
+        ...                 {
+        ...                     "name": "Stage case 1",
+        ...                     "eche": "Hello case 1",
+        ...                 },
+        ...             ],
+        ...         },
+        ...         {
+        ...             "else": [
+        ...                 {
+        ...                     "name": "Stage else",
+        ...                     "eche": "Hello case else",
+        ...                 },
+        ...             ],
+        ...         },
+        ...     ],
+        ... }
+
     """
 
     case: str = Field(description="A case condition for routing.")
-    match: list[Match] = Field(
+    match: list[Union[Match, Else]] = Field(
         description="A list of Match model that should not be an empty list.",
     )
     skip_not_match: bool = Field(
@@ -2975,46 +3111,117 @@ class CaseStage(BaseNestedStage):
         alias="skip-not-match",
     )
 
-    def _process_case(
+    @field_validator("match", mode="after")
+    def __validate_match(
+        cls, match: list[Union[Match, Else]]
+    ) -> list[Union[Match, Else]]:
+        """Validate the match field should contain only one Else model."""
+        c_else_case: int = 0
+        c_else_model: int = 0
+        for m in match:
+            if isinstance(m, Else):
+                if c_else_model:
+                    raise ValueError(
+                        "Match field should contain only one `Else` model."
+                    )
+                c_else_model += 1
+                continue
+            if isinstance(m, Match) and m.case == "_":
+                if c_else_case:
+                    raise ValueError(
+                        "Match field should contain only one else, '_', case."
+                    )
+                c_else_case += 1
+                continue
+        return match
+
+    def extract_stages_from_case(
+        self, case: StrOrNone, params: DictData
+    ) -> tuple[StrOrNone, list[Stage]]:
+        """Extract stage from case.
+
+        Args:
+            case (StrOrNone):
+            params (DictData):
+
+        Returns:
+            tuple[StrOrNone, list[Stage]]: A pair of case and stages.
+        """
+        _else_stages: Optional[list[Stage]] = None
+        stages: Optional[list[Stage]] = None
+
+        # NOTE: Start check the condition of each stage match with this case.
+        for match in self.match:
+
+            if isinstance(match, Else):
+                _else_stages: list[Stage] = match.other
+                continue
+
+            # NOTE: Store the else case.
+            if (c := match.case) == "_":
+                _else_stages: list[Stage] = match.stages
+                continue
+
+            _condition: str = param2template(c, params, extras=self.extras)
+            if pass_env(case) == pass_env(_condition):
+                stages: list[Stage] = match.stages
+                break
+
+        if stages is not None:
+            return case, stages
+
+        if _else_stages is None:
+            if not self.skip_not_match:
+                raise StageError(
+                    "This stage does not set else for support not match "
+                    "any case."
+                )
+            raise StageSkipError(
+                "Execution was skipped because it does not match any "
+                "case and the else condition does not set too."
+            )
+
+        # NOTE: Force to use the else when it does not match any case.
+        return "_", _else_stages
+
+    def _process_nested(
         self,
         case: str,
         stages: list[Stage],
         params: DictData,
-        run_id: str,
+        trace: Trace,
         context: DictData,
         *,
-        parent_run_id: Optional[str] = None,
         event: Optional[Event] = None,
     ) -> tuple[Status, DictData]:
         """Execute case.
 
-        :param case: (str) A case that want to execution.
-        :param stages: (list[Stage]) A list of stage.
-        :param params: (DictData) A parameter data.
-        :param run_id: (str)
-        :param context: (DictData)
-        :param parent_run_id: (str | None)
-        :param event: (Event) An Event manager instance that use to cancel this
-            execution if it forces stopped by parent execution.
+        Args:
+            case: (str) A case that want to execution.
+            stages: (list[Stage]) A list of stage.
+            params: (DictData) A parameter data.
+            trace: (Trace)
+            context: (DictData)
+            event: (Event) An Event manager instance that use to cancel this
+                execution if it forces stopped by parent execution.
 
-        :rtype: DictData
+        Returns:
+            DictData
         """
-        trace: TraceManager = get_trace(
-            run_id, parent_run_id=parent_run_id, extras=self.extras
-        )
-        trace.debug(f"[STAGE]: Execute Case: {case!r}")
+        trace.info(f"[NESTED]: Case: {case!r}")
         current_context: DictData = copy.deepcopy(params)
         current_context.update({"case": case})
         output: DictData = {"case": case, "stages": {}}
-        for stage in stages:
+        total_stage: int = len(stages)
+        skips: list[bool] = [False] * total_stage
+        for i, stage in enumerate(stages, start=0):
 
             if self.extras:
                 stage.extras = self.extras
 
             if event and event.is_set():
                 error_msg: str = (
-                    "Case-Stage was canceled from event that had set before "
-                    "stage case execution."
+                    f"Cancel case: {case!r} before start nested process."
                 )
                 return CANCEL, catch(
                     context=context,
@@ -3028,16 +3235,20 @@ class CaseStage(BaseNestedStage):
 
             rs: Result = stage.execute(
                 params=current_context,
-                run_id=parent_run_id,
+                run_id=trace.parent_run_id,
                 event=event,
             )
             stage.set_outputs(rs.context, to=output)
             stage.set_outputs(stage.get_outputs(output), to=current_context)
 
-            if rs.status == FAILED:
+            if rs.status == SKIP:
+                skips[i] = True
+                continue
+
+            elif rs.status == FAILED:
                 error_msg: str = (
-                    f"Case-Stage was break because it has a sub stage, "
-                    f"{stage.iden}, failed without raise error."
+                    f"Break case: {case!r} because nested stage: {stage.iden}, "
+                    f"failed."
                 )
                 return FAILED, catch(
                     context=context,
@@ -3048,9 +3259,25 @@ class CaseStage(BaseNestedStage):
                         "errors": StageError(error_msg).to_dict(),
                     },
                 )
-        return SUCCESS, catch(
+
+            elif rs.status == CANCEL:
+                error_msg: str = (
+                    f"Cancel case {case!r} after end nested process."
+                )
+                return CANCEL, catch(
+                    context=context,
+                    status=CANCEL,
+                    updated={
+                        "case": case,
+                        "stages": filter_func(output.pop("stages", {})),
+                        "errors": StageCancelError(error_msg).to_dict(),
+                    },
+                )
+
+        status: Status = SKIP if sum(skips) == total_stage else SUCCESS
+        return status, catch(
             context=context,
-            status=SUCCESS,
+            status=status,
             updated={
                 "case": case,
                 "stages": filter_func(output.pop("stages", {})),
@@ -3080,51 +3307,21 @@ class CaseStage(BaseNestedStage):
         Returns:
             Result: The execution result with status and context data.
         """
-        trace: TraceManager = get_trace(
+        trace: Trace = get_trace(
             run_id, parent_run_id=parent_run_id, extras=self.extras
         )
 
-        _case: StrOrNone = param2template(self.case, params, extras=self.extras)
-
-        trace.info(f"[STAGE]: Case: {_case!r}.")
-        _else: Optional[Match] = None
-        stages: Optional[list[Stage]] = None
-        for match in self.match:
-            if (c := match.case) == "_":
-                _else: Match = match
-                continue
-
-            _condition: str = param2template(c, params, extras=self.extras)
-            if stages is None and pass_env(_case) == pass_env(_condition):
-                stages: list[Stage] = match.stages
-
-        if stages is None:
-            if _else is None:
-                if not self.skip_not_match:
-                    raise StageError(
-                        "This stage does not set else for support not match "
-                        "any case."
-                    )
-                raise StageSkipError(
-                    "Execution was skipped because it does not match any "
-                    "case and the else condition does not set too."
-                )
-
-            _case: str = "_"
-            stages: list[Stage] = _else.stages
-
+        case: StrOrNone = param2template(self.case, params, extras=self.extras)
+        trace.info(f"[NESTED]: Get Case: {case!r}.")
+        case, stages = self.extract_stages_from_case(case, params=params)
         if event and event.is_set():
-            raise StageCancelError(
-                "Execution was canceled from the event before start "
-                "case execution."
-            )
-        status, context = self._process_case(
-            case=_case,
+            raise StageCancelError("Cancel before start case process.")
+        status, context = self._process_nested(
+            case=case,
             stages=stages,
             params=params,
-            run_id=run_id,
+            trace=trace,
             context=context,
-            parent_run_id=parent_run_id,
             event=event,
         )
         return Result(
@@ -3178,7 +3375,7 @@ class RaiseStage(BaseAsyncStage):
         Returns:
             Result: The execution result with status and context data.
         """
-        trace: TraceManager = get_trace(
+        trace: Trace = get_trace(
             run_id, parent_run_id=parent_run_id, extras=self.extras
         )
         message: str = param2template(self.message, params, extras=self.extras)
@@ -3209,7 +3406,7 @@ class RaiseStage(BaseAsyncStage):
         Returns:
             Result: The execution result with status and context data.
         """
-        trace: TraceManager = get_trace(
+        trace: Trace = get_trace(
             run_id, parent_run_id=parent_run_id, extras=self.extras
         )
         message: str = param2template(self.message, params, extras=self.extras)
@@ -3290,7 +3487,7 @@ class DockerStage(BaseStage):  # pragma: no cov
                 "by `pip install docker` first."
             ) from None
 
-        trace: TraceManager = get_trace(
+        trace: Trace = get_trace(
             run_id, parent_run_id=parent_run_id, extras=self.extras
         )
         client = DockerClient(
@@ -3390,7 +3587,7 @@ class DockerStage(BaseStage):  # pragma: no cov
         Returns:
             Result: The execution result with status and context data.
         """
-        trace: TraceManager = get_trace(
+        trace: Trace = get_trace(
             run_id, parent_run_id=parent_run_id, extras=self.extras
         )
         trace.info(f"[STAGE]: Docker: {self.image}:{self.tag}")
@@ -3403,8 +3600,11 @@ class VirtualPyStage(PyStage):  # pragma: no cov
     """
 
     version: str = Field(
-        default="3.9",
-        description="A Python version that want to run.",
+        default=__python_version__,
+        description=(
+            "A Python version that want to run. It will use supported version "
+            f"of this package by default, {__python_version__}."
+        ),
     )
     deps: list[str] = Field(
         description=(
@@ -3427,11 +3627,12 @@ class VirtualPyStage(PyStage):  # pragma: no cov
             The format of Python dependency was followed by the `uv`
         recommended.
 
-        :param py: A Python string statement.
-        :param values: A variable that want to set before running this
-        :param deps: An additional Python dependencies that want install before
-            run this python stage.
-        :param run_id: (StrOrNone) A running ID of this stage execution.
+        Args:
+            py: A Python string statement.
+            values: A variable that want to set before running this
+            deps: An additional Python dependencies that want install before
+                run this python stage.
+            run_id: (StrOrNone) A running ID of this stage execution.
         """
         run_id: str = run_id or uuid.uuid4()
         f_name: str = f"{run_id}.py"
@@ -3500,7 +3701,7 @@ class VirtualPyStage(PyStage):  # pragma: no cov
         Returns:
             Result: The execution result with status and context data.
         """
-        trace: TraceManager = get_trace(
+        trace: Trace = get_trace(
             run_id, parent_run_id=parent_run_id, extras=self.extras
         )
         run: str = param2template(dedent(self.run), params, extras=self.extras)
@@ -3546,6 +3747,59 @@ class VirtualPyStage(PyStage):  # pragma: no cov
             extras=self.extras,
         )
 
+    async def async_process(
+        self,
+        params: DictData,
+        run_id: str,
+        context: DictData,
+        *,
+        parent_run_id: Optional[str] = None,
+        event: Optional[Event] = None,
+    ) -> Result:
+        raise NotImplementedError(
+            "Async process of Virtual Python stage does not implement yet."
+        )
+
+
+NestedStage = Annotated[
+    Union[
+        BashStage,
+        CallStage,
+        PyStage,
+        VirtualPyStage,
+        RaiseStage,
+        DockerStage,
+        TriggerStage,
+        EmptyStage,
+        CaseStage,
+        ForEachStage,
+        UntilStage,
+    ],
+    Field(
+        union_mode="smart",
+        description="A nested-stage allow list",
+    ),
+]  # pragma: no cov
+
+
+ActionStage = Annotated[
+    Union[
+        BashStage,
+        CallStage,
+        VirtualPyStage,
+        PyStage,
+        RaiseStage,
+        DockerStage,
+        EmptyStage,
+    ],
+    Field(
+        union_mode="smart",
+        description=(
+            "An action stage model that allow to use with nested-stage model."
+        ),
+    ),
+]  # pragma: no cov
+
 
 # NOTE:
 #   An order of parsing stage model on the Job model with `stages` field.
@@ -3554,18 +3808,14 @@ class VirtualPyStage(PyStage):  # pragma: no cov
 #
 Stage = Annotated[
     Union[
-        DockerStage,
-        BashStage,
-        CallStage,
-        TriggerStage,
+        # NOTE: Nested Stage.
         ForEachStage,
         UntilStage,
         ParallelStage,
         CaseStage,
-        VirtualPyStage,
-        PyStage,
-        RaiseStage,
-        EmptyStage,
+        TriggerStage,
+        # NOTE: Union with the action stage.
+        ActionStage,
     ],
     Field(
         union_mode="smart",