simplibs-actions 0.1.0__py3-none-any.whl

simplibs/actions/__init__.py

@@ -0,0 +1,103 @@
+# 1. Base Class
+from .base_class import Action
+
+# 2. Composition Classes
+from .containers.operators.compose_class import ParallelCompose, SequenceCompose
+
+# 3. Primary Containers & Aggregated Aliases Namespace
+from .containers import (
+    aliases,
+    branch,
+    constant,
+    fallback,
+    for_each,
+    guard,
+    identity,
+    lambda_action,
+    log_action,
+    parallel,
+    retry,
+    sequence,
+    tap,
+)
+
+# 4. Creators & Decorators
+from .creator import create_action
+from .decorator import to_action
+
+
+__all__ = [
+    # Base
+    "Action",
+    # Composition Classes
+    "ParallelCompose",
+    "SequenceCompose",
+    # Flow Control Containers
+    "branch",
+    "for_each",
+    "guard",
+    # Operator Containers
+    "fallback",
+    "parallel",
+    "sequence",
+    # Primitive Containers
+    "constant",
+    "identity",
+    # Wrapper Containers
+    "lambda_action",
+    "log_action",
+    "retry",
+    "tap",
+    # Factory & Decorator
+    "create_action",
+    "to_action",
+    # Aggregated Aliases Namespace
+    "aliases",
+]
+
+
+_DESIGN_NOTES = """
+# Main Simplibs Actions Package
+
+## Purpose
+Root public entry point for `simplibs-actions`. Exposes the complete high-level API
+surface for constructing, composing, decorating, and executing data transformation pipelines.
+
+## Public Components Registry
+
+| Component         | Type     | Origin Sub-Package | Description                                                               |
+| :---------------- | :------- | :----------------- | :------------------------------------------------------------------------ |
+| `Action`          | Class    | `base_class`       | Core abstract base class defining operator composition and execution.     |
+| `SequenceCompose` | Class    | `containers`       | Intermediate lazy composition wrapper created via `>>` / `+` operators.   |
+| `ParallelCompose` | Class    | `containers`       | Intermediate lazy composition wrapper created via `&` operator.           |
+| `branch`          | Function | `containers`       | Soft conditional branching container (`if/then/else`).                    |
+| `for_each`        | Function | `containers`       | Collection-processing container over input iterables.                      |
+| `guard`           | Function | `containers`       | Hard gate container validating data against a rule before proceeding.     |
+| `fallback`        | Function | `containers`       | Exception mitigation container providing alternative branch execution.    |
+| `parallel`        | Function | `containers`       | Parallel branch execution container returning tuple of outputs.           |
+| `sequence`        | Function | `containers`       | Sequential step execution container feeding results left-to-right.        |
+| `constant`        | Function | `containers`       | Primitive container ignoring input and returning a fixed value.           |
+| `identity`        | Function | `containers`       | Primitive container returning input data unchanged.                       |
+| `lambda_action`   | Function | `containers`       | Wrapper transforming raw single-argument callables into Actions.          |
+| `log_action`      | Function | `containers`       | Wrapper logging pipeline data without modifying the payload.             |
+| `retry`           | Function | `containers`       | Wrapper executing action multiple times on specified exception catches.   |
+| `tap`             | Function | `containers`       | Wrapper executing side-effect functions while passing input through.      |
+| `create_action`   | Function | `creator`          | Low-level factory function synthesizing typed `Action` classes/instances. |
+| `to_action`       | Function | `decorator`        | High-level decorator turning standard callables into two-phase Actions.   |
+| `aliases`         | Instance | `containers`       | Aggregated namespace offering descriptive naming alternatives for containers|
+
+
+## Architectural Design Decisions
+
+1. **Single Source of Truth for Aliases**: The `aliases` namespace instance is instantiated strictly
+   once within `containers/__init__.py` and simply re-exported here. This guarantees object identity
+   (`actions.aliases is actions.containers.aliases`) and eliminates duplication.
+2. **Flattened Public API**: All primary building blocks are re-exported at the package root
+   so downstream code can import directly from `simplibs.actions`.
+3. **Explicit Alias Namespacing**: Aliases are intentionally contained inside the `aliases`
+   object namespace to prevent polluting the top-level namespace while providing auto-complete
+   and clear intent (`actions.aliases.run_in_sequence`).
+4. **Isolation of Testing Tools**: Testing utilities (`assert_action`, `assert_action_alias`)
+   are strictly excluded from this root package to keep production imports light and avoid
+   unnecessary test-framework dependencies in non-testing environments.
+"""

simplibs/actions/base_class/Action.py

@@ -0,0 +1,188 @@
+from abc import ABC, abstractmethod
+from typing import Any
+from simplibs.rules import Rule
+# Inners
+from ._validations import raise_invalid_action_target
+
+
+class Action(ABC):
+    """Abstract base class for all operative actions and transformations.
+
+    `__call__` is the sole abstract method — unlike `Rule` (where
+    `is_valid` is the answer to a question and `__call__` is just
+    convenient sugar over it), for an `Action` being callable IS the
+    whole point, so no second method (`execute`/`act`) is needed at the
+    base level. Concrete subclasses arise in two ways: hand-written
+    containers implementing `__call__` directly (e.g. `SequenceCompose`/
+    `ParallelCompose`, which need bespoke flattening logic no generic
+    factory can derive on its own), or generated from an ordinary
+    function via `create_action`/`to_action` (e.g. `guard`, `branch`,
+    `sequence`, `fallback` — nearly everything else).
+    """
+
+    # Hook signaling to Rule that this object is not meant to be silently
+    # absorbed by `Rule.__and__`/`__or__` as a plain predicate — see
+    # Rule.py's own design notes for the full rationale.
+    __not_rule__ = True
+
+    # ----------------------------------------------------------------------
+    # 1) Executable Interface
+    # ----------------------------------------------------------------------
+
+    @abstractmethod
+    def __call__(self, data: Any, /) -> Any:
+        """Run this action over `data` and return the result."""
+        raise NotImplementedError
+
+    # ----------------------------------------------------------------------
+    # 2) Operator-Based Composition — Forward Direction (self on the left)
+    # ----------------------------------------------------------------------
+
+    def then(self, next_step: Any) -> "Action":
+        """Chains this action with a subsequent action, rule, or callable."""
+        from ..containers.operators.compose_class import SequenceCompose
+        return SequenceCompose.compose(first=self, second=self.resolve_action(next_step))
+
+    def __rshift__(self, next_step: Any) -> "Action":
+        """Chains this action with a subsequent step via the `>>` operator."""
+        return self.then(next_step)
+
+    def __and__(self, other: Any) -> "Action":
+        """Executes actions in parallel over identical input data: `actionA & actionB`."""
+        from ..containers.operators.compose_class import ParallelCompose
+        return ParallelCompose.compose(first=self, second=self.resolve_action(other))
+
+    def __or__(self, other: Any) -> "Action":
+        """Fallback handling: executes `other` if this action fails: `actionA | actionB`."""
+        from ..containers.operators import fallback
+        return fallback(action=self, on_error=self.resolve_action(other))
+
+    # ----------------------------------------------------------------------
+    # 3) Operator-Based Composition — Reflected Direction (self on the right)
+    # ----------------------------------------------------------------------
+    #
+    # Triggered when `Rule.__and__`/`__or__` declines the combination
+    # because of `__not_rule__` (see Rule.py's own design notes) and
+    # Python falls back to `other.__rand__`/`__ror__`/`__rrshift__` — or
+    # when `other` is a plain callable/Rule with no operator of its own
+    # at all. Each method simply wraps `other` via `resolve_action` and
+    # hands off to the forward operator — one place of truth, no
+    # duplicated container-construction logic.
+
+    def __rand__(self, other: Any) -> "Action":
+        """Supports `rule & action` — verify AND execute in parallel."""
+        return self.resolve_action(other) & self
+
+    def __ror__(self, other: Any) -> "Action":
+        """Supports `rule | action` — verify, or run a fallback action on failure."""
+        return self.resolve_action(other) | self
+
+    def __rrshift__(self, other: Any) -> "Action":
+        """Supports `rule >> action` — verify the rule, then continue with the action."""
+        return self.resolve_action(other) >> self
+
+    # ----------------------------------------------------------------------
+    # 4) Resolution Helper
+    # ----------------------------------------------------------------------
+
+    @staticmethod
+    def resolve_action(obj: Any) -> "Action":
+        """Convert an Action, a Rule, or a plain callable into an Action instance.
+
+        Args:
+            obj: An `Action` instance (returned unchanged), a `Rule`
+                instance (wrapped into `guard`), or any other callable
+                (wrapped into `lambda_action`).
+
+        Returns:
+            An `Action` instance ready to be composed.
+
+        Raises:
+            TypeError: If `obj` is neither an `Action`, a `Rule`, nor callable.
+        """
+
+        # 1. Already an Action instance — return it unchanged
+        if isinstance(obj, Action):
+            return obj
+
+        # 2. A Rule instance — wrap it into the hard-gate container
+        if isinstance(obj, Rule):
+            from ..containers.flow_control import guard
+            return guard(rule=obj)
+
+        # 3. Any other callable — wrap it into the plain-transformer adapter
+        if callable(obj):
+            from ..containers.wrappers import lambda_action
+            return lambda_action(func=obj)
+
+        # 4. Anything else is not a valid Action target
+        return raise_invalid_action_target(obj)
+
+
+_DESIGN_NOTES = """
+# Action — base abstract class (redesigned)
+
+## Why only `__call__`, no `execute`/`act` at the base level
+
+An earlier version had `execute` as the abstract method and `__call__` as
+a thin wrapper over it — mirroring `Rule.is_valid`/`__call__`. That
+mirroring turned out to be a mistake: for `Rule`, `is_valid` is the
+*answer to a question* and callability is a convenience on top; for
+`Action`, callability itself IS the substance — an action *is* a
+function with one main input. The second method was never actually
+needed, and once caused a real bug (a class generated by `create_action`
+had `__call__`, but the base `Action` required `execute` — the class
+could not be instantiated at all). Collapsing to a single abstract
+`__call__` removes that mismatch structurally, not with a patch.
+
+Subclasses arise in two ways:
+* **hand-written** — `SequenceCompose`/`ParallelCompose` implement
+  `__call__` directly (inherited from their `create_action`-generated
+  base, `sequence`/`parallel`) because they need bespoke flattening
+  logic (`compose`) that no generic factory can derive on its own;
+* **via `create_action`/`to_action`** — nearly everything else (`guard`,
+  `branch`, `for_each`, `sequence`, `parallel`, `fallback`, `identity`,
+  `constant`, `lambda_action`, `log_step`, `retry`, `tap`). There,
+  `act`/`__init__`/`__call__` are implementation details of the
+  *generator* (needed for the separate `validate_call`/`log_this`
+  wrapping of each), not a requirement of the base class itself.
+
+## Reflected operators — `__rand__`/`__ror__`/`__rrshift__`
+
+Triggered exclusively by the `__not_rule__` hook on the `Rule` side (see
+`Rule.py`'s own design notes) — `rule & action` first hits
+`Rule.__and__`, which returns `NotImplemented`, and only then does Python
+try `action.__rand__(rule)`.
+
+The semantics of all three are derived from what the `guard` container
+does (pass through unchanged if the `Rule` holds, otherwise raise):
+* `rule >> action` — check, then continue (sequence).
+* `rule & action` — check AND run the action (in parallel; both must
+  succeed — the spirit of `AllOf`, shifted from "predicate AND
+  predicate" to "gate AND action").
+* `rule | action` — check, and on failure run the action instead (the
+  spirit of `AnyOf` — at least one path must succeed, only the first
+  path is a hard gate).
+
+All three are implemented as the same one-line pattern —
+`self.resolve_action(other) <op> self` — wrap the left-hand operand,
+hand off to the forward operator. No second copy of any container's
+construction logic; one place of truth covers both `rule & action` and
+`action & action`.
+
+**A typing cost, not a behavioral one:** `Rule.__and__`/`__or__` can now
+return either `Rule` or `Action`, depending on the right-hand operand's
+type. This is already handled on the `Rule` side via a structural
+`_NotARule` `Protocol` plus `@overload` pairs on every binary operator
+(`__and__`/`__or__`/`__rand__`/`__ror__`) — see `Rule.py`'s own design
+notes, section 6, for why a `Protocol` is used instead of importing
+`Action` directly (keeping `simplibs-validate` independent of
+`simplibs-actions`, even for typing purposes).
+
+## `__not_rule__` remains unchanged
+
+Still the single hook driving this entire asymmetry — `Rule` declines to
+treat `Action` as a predicate, `Action` supplies its own, meaningful
+interpretation instead. See `Rule.py`'s design notes for the complete
+rationale.
+"""

simplibs/actions/base_class/__init__.py

@@ -0,0 +1,17 @@
+from .Action import Action
+
+
+_DESIGN_NOTES = """
+# Action Base Sub-Package
+
+## Purpose
+Provides the abstract base class `Action` that defines core pipeline execution,
+dunder-method composition, representation, and polymorphic resolution for all
+action types in the package.
+
+## Components Registry
+
+| Component | Type  | Description                                                                     |
+| :-------- | :---- | :------------------------------------------------------------------------------ |
+| `Action`  | Class | Base class for callable data transformation units with operator composition.     |
+"""

simplibs/actions/base_class/_validations/__init__.py

@@ -0,0 +1,16 @@
+from .raise_invalid_action_target import raise_invalid_action_target
+
+
+_DESIGN_NOTES = """
+# Action Base Validations Sub-Package
+
+## Purpose
+Internal diagnostic and validation helpers used by the `Action` base class to enforce
+type safety and provide formatted diagnostics during action resolution and composition.
+
+## Internal Components Registry
+
+| Component                      | Type     | Description                                                                 |
+| :----------------------------- | :------- | :-------------------------------------------------------------------------- |
+| `raise_invalid_action_target`  | Function | Raises a formatted `ParamError` when an object cannot be converted to Action.|
+"""

simplibs/actions/base_class/_validations/raise_invalid_action_target.py

@@ -0,0 +1,54 @@
+from typing import Any, NoReturn
+from simplibs.exception import ParamError
+
+
+def raise_invalid_action_target(obj: Any) -> NoReturn:
+    """Raises a ParamError when an object cannot be resolved into an Action.
+
+    Args:
+        obj: The candidate target object that failed resolution checks.
+
+    Raises:
+        ParamError: Unconditionally raised with diagnostic context.
+    """
+    raise ParamError(
+        error_name="INVALID_ACTION_TARGET",
+        label="action target candidate",
+        value=type(obj).__name__,
+        problem=(
+            f"Object of type '{type(obj).__name__}' cannot be converted into an Action.",
+            "Action resolution expects an Action instance, a Rule, or any Callable.",
+        ),
+        expected="An Action instance, a Rule, or a callable function/object.",
+        how_to_fix=(
+            "Ensure you pass a valid callable entity to the operator or resolution helper.",
+            "If passing a custom class or object, ensure it is callable (implements __call__) "
+            "or inherits from Action / Rule.",
+        ),
+        exception=TypeError,
+    )
+
+
+_DESIGN_NOTES = """
+# raise_invalid_action_target — Action Resolution Failure Diagnostic
+
+## Purpose
+Provides a standard, highly diagnostic `ParamError` exception when an object
+passed to `Action.resolve_action` or compositional operators (`|`, `>>`) cannot
+be converted into a valid `Action` instance.
+
+---
+
+## 1. Unified Exception Interface
+
+By delegating invalid resolution reporting to a dedicated function, all
+composition and resolution entry points share identical error diagnostics,
+labels, and remediation instructions.
+
+---
+
+## 2. Dynamic Type Inspection
+
+Reflects the actual type of the received `obj` in the diagnostic message to
+give clear feedback to the developer about what unsupported type was provided.
+"""

simplibs/actions/containers/__init__.py

@@ -0,0 +1,88 @@
+# Composition Classes
+from .operators.compose_class import ParallelCompose, SequenceCompose
+
+# Flow Control Containers
+from .flow_control import branch, for_each, guard
+
+# Operator Containers
+from .operators import fallback, parallel, sequence
+
+# Primitive Containers
+from .primitives import constant, identity
+
+# Wrapper Containers
+from .wrappers import lambda_action, log_action, retry, tap
+
+# Aliases Sub-Package / Namespace Import
+from . import flow_control, operators, primitives, wrappers
+
+# Aggregated Aliases Namespace
+class _Aliases:
+    """Namespace grouping all alias functions across container sub-packages."""
+    # Flow Control Aliases
+    apply_to_each = flow_control.aliases.apply_to_each
+    conditional_action = flow_control.aliases.conditional_action
+    guarded_action = flow_control.aliases.guarded_action
+
+    # Operator Aliases
+    run_in_parallel = operators.aliases.run_in_parallel
+    run_in_sequence = operators.aliases.run_in_sequence
+    try_or_fallback = operators.aliases.try_or_fallback
+
+    # Primitive Aliases
+    pass_through = primitives.aliases.pass_through
+    replace_with = primitives.aliases.replace_with
+
+    # Wrapper Aliases
+    callable_action = wrappers.aliases.callable_action
+    log_step = wrappers.aliases.log_step
+    retry_on_failure = wrappers.aliases.retry_on_failure
+    run_side_effect = wrappers.aliases.run_side_effect
+
+
+aliases = _Aliases()
+
+
+__all__ = [
+    # Composition Classes
+    "ParallelCompose",
+    "SequenceCompose",
+    # Flow Control
+    "branch",
+    "for_each",
+    "guard",
+    # Operators
+    "fallback",
+    "parallel",
+    "sequence",
+    # Primitives
+    "constant",
+    "identity",
+    # Wrappers
+    "lambda_action",
+    "log_action",
+    "retry",
+    "tap",
+    # Aliases
+    "aliases",
+]
+
+
+_DESIGN_NOTES = """
+# Main Action Containers Package
+
+## Purpose
+The `containers` package forms the core structural foundation of the action system. It provides
+a rich set of higher-order action containers that manage execution flow, error handling, batching,
+parallelism, side effects, and pipeline primitive building blocks.
+
+## Internal Sub-Packages Registry
+
+| Sub-Package    | Type               | Description                                                                     |
+| :------------- | :----------------- | :------------------------------------------------------------------------------ |
+| `_helpers`     | Internal Helpers   | Private utilities for action normalization, inspection, and sequence unwrapping.|
+| `flow_control` | Public Containers  | Branching (`branch`), iteration (`for_each`), and conditional evaluation (`guard`).|
+| `operators`    | Public Containers  | Main composition containers (`sequence`, `parallel`, `fallback`) and classes.  |
+| `primitives`   | Public Containers  | Fundamental pipeline building blocks (`identity`, `constant`).                  |
+| `wrappers`     | Public Containers  | Decorating and utility containers (`lambda_action`, `log_action`, `retry`, `tap`).|
+"""

simplibs/actions/containers/_helpers/__init__.py

@@ -0,0 +1,18 @@
+from .as_action import as_action
+from .as_predicate import as_predicate
+
+
+_DESIGN_NOTES = """
+# Action Container Helpers Sub-Package
+
+## Purpose
+Internal resolution and adaptation helpers used across action containers to normalize
+arbitrary runnables into unified `Action` instances and condition inputs into executable predicates.
+
+## Internal Components Registry
+
+| Component      | Type     | Description                                                                     |
+| :------------- | :------- | :------------------------------------------------------------------------------ |
+| `as_action`    | Alias    | Direct shorthand for `Action.resolve_action` to normalize runnables to Actions. |
+| `as_predicate` | Function | Normalizes `Rule` instances or callables into unified boolean-returning methods.|
+"""

simplibs/actions/containers/_helpers/as_action.py

@@ -0,0 +1,31 @@
+# Outers
+from ...base_class import Action
+
+
+as_action = Action.resolve_action
+"""Module-level alias for `Action.resolve_action`.
+
+Provides a clean, self-describing shorthand within container implementations,
+eliminating the need to repeatedly access the static method via `Action.resolve_action(...)`.
+"""
+
+
+_DESIGN_NOTES = """
+# as_action — module-level alias for Action.resolve_action
+
+## Purpose
+Every container that accepts "something runnable" (`then_branch`, `action`,
+`on_error`, individual `sequence`/`parallel` steps...) needs to resolve a
+given object into a uniform `Action` instance.
+`Action.resolve_action` houses the core resolution logic. `as_action` serves
+as a module-level alias to avoid repeated, verbose access via the class name
+(`Action.resolve_action`) across container modules, making the call sites
+substantially more self-describing and expressive.
+
+## Why a direct assignment alias, not a wrapping function
+No wrapper overhead or duplicate logic — all resolution mechanics (detecting
+`Action`/`Rule`/callable and adapting accordingly) remain strictly encapsulated
+inside `Action.resolve_action`. Assigning `as_action = Action.resolve_action`
+directly guarantees zero execution overhead while retaining full IDE signature
+hints, docstrings, and type safety.
+"""

simplibs/actions/containers/_helpers/as_predicate.py

@@ -0,0 +1,58 @@
+from typing import Any, Callable
+from simplibs.rules import Rule
+# Inners
+from .validations import raise_invalid_predicate
+
+
+def as_predicate(condition: Any) -> Callable[[Any], bool]:
+    """Normalize a Rule instance or a plain callable into a single bool-returning call.
+
+    Replaces repeated duck-typing checks in `guard`/`branch` with a single
+    source of truth — aligning with the helper pattern used across the library.
+    """
+
+    # 1. Official Rule instance -> direct method reference (fastest path)
+    if isinstance(condition, Rule):
+        return condition.is_valid
+
+    # 2. Plain lambda / function / any callable
+    if callable(condition):
+        # noinspection PyTypeChecker
+        return condition
+
+    # 3. Structured exception helper for invalid predicate inputs
+    raise_invalid_predicate(condition)
+
+
+_DESIGN_NOTES = """
+# as_predicate — shared condition adapter
+
+## Purpose
+`guard` and `branch` both need the same thing: "give me a function that
+returns bool for `data`", whether `condition`/`rule` arrived as a `Rule`
+instance (`is_valid`) or a plain callable. Without this helper, both
+containers would carry duplicate validation and resolution logic. Using an
+explicit `isinstance(condition, Rule)` check ensures fast and type-safe
+method binding.
+
+## Exception Handling
+When an invalid predicate (neither a `Rule` nor a callable) is passed,
+`raise_invalid_predicate` is triggered to throw a structured exception,
+keeping validation error formats consistent across the library.
+
+## Why it doesn't special-case Action
+`Action.__call__` is callable too, but this helper treats it like any
+other callable — it falls into the `callable(condition)` branch and gets
+invoked directly. The result (`Any`, not necessarily `bool`) is then
+evaluated by ordinary Python truthiness in `guard`/`branch`. This works,
+but gives no guarantee the return value is meaningful as a condition —
+left unaddressed here on purpose; if it ever needs constraining, that
+belongs in `guard`/`branch` themselves, not this shared helper.
+
+## Relationship to as_action
+Sibling in this same `_helpers` package — `as_predicate` answers "is this
+true?", `as_action` answers "run this over data". Split into two files,
+not one `_helpers.py`, since each serves a different group of containers,
+consistent with the "one item per file" convention across the rest
+of the library.
+"""

simplibs/actions/containers/_helpers/validations/__init__.py

@@ -0,0 +1,16 @@
+from .raise_invalid_predicate import raise_invalid_predicate
+
+
+_DESIGN_NOTES = """
+# Action Container Helper Validations Sub-Package
+
+## Purpose
+Internal structured exception emission helpers dedicated to validating condition
+and predicate inputs used by container helper functions.
+
+## Internal Components Registry
+
+| Component                 | Type     | Description                                                                     |
+| :------------------------ | :------- | :------------------------------------------------------------------------------ |
+| `raise_invalid_predicate` | Function | Raises a structured `ParamError` when an input is neither a `Rule` nor callable.|
+"""

simplibs/actions/containers/_helpers/validations/raise_invalid_predicate.py

@@ -0,0 +1,42 @@
+from typing import Any, NoReturn
+from simplibs.exception import ParamError
+
+
+def raise_invalid_predicate(condition: Any) -> NoReturn:
+    """Raise a ParamError if the given condition is neither a Rule nor a Callable."""
+
+    # 1. Raise structured ParamError wrapping a TypeError exception
+    raise ParamError(
+        error_name="INVALID_PREDICATE_TARGET",
+        label="condition / rule",
+        value=type(condition).__name__,
+        problem=(
+            f"Expected a Rule or Callable, got: {type(condition).__name__}.",
+            "The passed object cannot be evaluated as a predicate or condition.",
+        ),
+        expected="A Rule instance or a callable function (Callable).",
+        how_to_fix=(
+            "Ensure that you pass a Rule object or a callable function returning a boolean as the condition.",
+        ),
+        exception=TypeError,
+    )
+
+
+_DESIGN_NOTES = """
+# raise_invalid_predicate — structured validation error helper
+
+## Purpose
+Provides a centralized, structured exception emitter when a non-predicate value
+(neither a `Rule` instance nor a callable object) is supplied where a condition
+is expected (e.g., in `guard` or `branch` containers).
+
+## Target Code & Integration
+- **Caller**: `as_predicate` helper in `containers/_helpers/as_predicate.py`.
+- **Target Context**: Triggered during container setup/execution when normalizing
+  input arguments passed as rules or conditional branches.
+
+## Why a separate helper
+Isolating exception construction keeps the core `as_predicate` resolution loop
+lean, fast, and easy to read, while enforcing consistent structured error messaging
+(`ParamError`) across the library.
+"""

simplibs/actions/containers/flow_control/__init__.py

@@ -0,0 +1,21 @@
+from . import aliases
+from .branch import branch
+from .for_each import for_each
+from .guard import guard
+
+
+_DESIGN_NOTES = """
+# Flow Control Containers Sub-Package
+
+## Purpose
+Provides flow control containers that manage data routing, conditional execution,
+and collection iteration within action pipelines.
+
+## Internal Components Registry
+
+| Component  | Type      | Description                                                                     |
+| :--------- | :-------- | :------------------------------------------------------------------------------ |
+| `branch`   | Container | Soft conditional branching (routes data or passes through unchanged).           |
+| `for_each` | Container | Iterative execution (applies an action to each item of an iterable).            |
+| `guard`    | Container | Hard gate verification (passes data if rule holds, otherwise raises).           |
+"""